docs: add api-docs to the appConfig getters

Author: nikomakela

README.md

@@ -69,6 +69,10 @@ All the applications inside the monorepo are sharing the similar Apollo-Router i
 
 > Apps should not depend on apps, they can depend on packages
 
+#### Configuration
+
+The application and proxy configuration is done via the AppConfig -file as much as possible, so there would be a single point for all the configuration.
+
 #### Shared packages
 
 - [packages/eslint-config-bases](./packages/eslint-config-bases): [README](./packages/eslint-config-bases/README.md) | [CHANGELOG](./packages/eslint-config-bases/CHANGELOG.md)

apps/events-helsinki/README.md

@@ -91,15 +91,15 @@ Events uses a lot of the components from the HCRC-lib. For example the article a
 
 There are 2 Apollo-clients in implemented: an Apollo-client for _`Headless CMS` to fetch articles and dynamic pages_ from the CMS and an Apollo-client for _`LinkedEvents` to fetch events_ from the Event-proxy. They both contains URL-fields that are targeted to an external source. Since the content is wanted to be rendered inside the Events app, the URLs needs to be transformed so that they are pointing to an internal path. An Apollo Link is a create place to do the transformation, when the URL context is known. Therefore, the URL should include a hint of the context, e.g a context path like `/articles*` or `/pages*` or a domain e.g `linkedvents.hel.fi`.
 
-The transformation table is in the `AppConfig.ts`:
+The transformation table is in the [AppConfig.ts](./src/domain/app/AppConfig.ts) :
 
 ```typescript
 class AppConfig {
   // ...
   static get linkedEventsEventEndpoint() {
     return getEnvOrError(
       publicRuntimeConfig.linkedEvents,
-      'LINKEDEVENTS_EVENT_ENDPOINT'
+      "LINKEDEVENTS_EVENT_ENDPOINT"
     );
   }
   static get cmsArticlesContextPath() {
@@ -124,6 +124,10 @@ class AppConfig {
 }
 ```
 
+## Application configuration
+
+The application configuration is done via the [AppConfig.ts](./src/domain/app/AppConfig.ts) as much as possible, so there would be a single point to configure it.
+
 ## Contact
 
 City of Helsinki Slack channel _NO CHANNEL YET?_ (use #hobbieshelsinki)

apps/events-helsinki/src/domain/app/AppConfig.ts

@@ -7,69 +7,137 @@ import { ROUTES } from '../../constants';
 const { publicRuntimeConfig } = getConfig();
 
 class AppConfig {
+  /**
+   * The base URL of the CMS.
+   *
+   * Example usage:
+   * The headless CMS adds it's own domain (and possibly also the root path)
+   * to every link that it returns through API. The cmsOrigin-getter is used
+   * in the link manipulation so that we can remove the CMS origin from the link
+   * inside the app.
+   * */
   static get cmsOrigin() {
     return getEnvOrError(publicRuntimeConfig.cmsOrigin, 'CMS_ORIGIN');
   }
 
+  /**
+   * The endpoint for the Apollo federation Router.
+   * Can be used for example to configure the Apollo-client.
+   * */
   static get federationGraphqlEndpoint() {
     return getEnvOrError(
       publicRuntimeConfig.federationRouter,
       'FEDERATION_ROUTER_ENDPOINT'
     );
   }
 
+  /**
+   * The base URL of the LinkedEvents event-API.
+   *
+   * Example usage:
+   * The headless CMS returns the LinkedEvent URLs through the API.
+   * The linkedEventsEventEndpoint-getter is used
+   * in the link manipulation so that we can remove the LinkedEvents origin from the link
+   * inside the app.
+   * */
   static get linkedEventsEventEndpoint() {
     return getEnvOrError(
       publicRuntimeConfig.linkedEvents,
       'LINKEDEVENTS_EVENT_ENDPOINT'
     );
   }
 
+  /**
+   * The own origin of the app.
+   * Can be used e.g. to configure the Headless CMS React Components -library.
+   * */
   static get origin() {
     return getEnvOrError(
       process.env.NEXT_PUBLIC_APP_ORIGIN,
       'NEXT_PUBLIC_APP_ORIGIN'
     );
   }
 
+  /**
+   * The app uses multiple domains from the Headless CMS API.
+   * It serves posts / articles from 1 root and e.g the pages from another.
+   * The CMS needs to be configured so, that the URI of an object it serves
+   * contains the context. For example an URL to an article could contain
+   * a static path `/articles` in it's pathname, so it's easily recognizible as an article URL.
+   * The application can then use a PostQuery to fetch the related information from an external service.
+   */
   static get cmsArticlesContextPath() {
     return process.env.NEXT_PUBLIC_CMS_ARTICLES_CONTEXT_PATH ?? '/articles';
   }
 
+  /**
+   * The app uses multiple domains from the Headless CMS API.
+   * It serves posts / articles from 1 root and e.g the pages from another.
+   * The CMS needs to be configured so, that the URI of an object it serves
+   * contains the context. For example an URL to an page could contain
+   * a static path `/pages` in it's pathname, so it's easily recognizible as a page URL.
+   * The application can then use a PageQuery to fetch the related information from an external service.
+   */
   static get cmsPagesContextPath() {
     return process.env.NEXT_PUBLIC_CMS_PAGES_CONTEXT_PATH ?? '/pages';
   }
 
+  /** The supported LinkedEvent event types. */
   static get supportedEventTypes() {
     return [EventTypeId.General];
   }
 
+  /**
+   * The generally used date format.
+   * Helsinki services are recommended to follow the Finnish date and time locale -
+   * even if the user is using some other language.
+   * Follow these guidelines when presenting date and time in your services.
+   * https://hds.hel.fi/foundation/guidelines/data-formats/
+   */
   static get dateFormat() {
     return 'dd.MM.yyyy';
   }
 
+  /**
+   * The generally used short date time format.
+   * Helsinki services are recommended to follow the Finnish date and time locale -
+   * even if the user is using some other language.
+   * Follow these guidelines when presenting date and time in your services.
+   * https://hds.hel.fi/foundation/guidelines/data-formats/
+   */
   static get shortDatetimeFormat() {
     return 'dd.MM.yyyy HH:mm';
   }
 
+  /**
+   * The generally used long date time format.
+   * Helsinki services are recommended to follow the Finnish date and time locale -
+   * even if the user is using some other language.
+   * Follow these guidelines when presenting date and time in your services.
+   * https://hds.hel.fi/foundation/guidelines/data-formats/
+   */
   static get datetimeFormat() {
     return 'dd.MM.yyyy HH:mm:ss';
   }
 
+  /** Should the application allow HTTP-connections? */
   static get allowUnauthorizedRequests() {
     return Boolean(
       parseEnvValue(process.env.NEXT_PUBLIC_ALLOW_UNAUTHORIZED_REQUESTS)
     );
   }
 
+  /** A global debug switch for development purposes. */
   static get debug() {
     return Boolean(parseEnvValue(process.env.NEXT_PUBLIC_DEBUG));
   }
 
+  /** A default HDS theme for the buttons. https://hds.hel.fi/foundation/design-tokens/colour. */
   static get defaultButtonTheme(): CommonButtonProps['theme'] {
     return 'default';
   }
 
+  /** A primary variant for the buttons. https://hds.hel.fi/foundation/design-tokens/colour. */
   static get defaultButtonVariant(): CommonButtonProps['variant'] {
     return 'success';
   }
@@ -107,6 +175,10 @@ class AppConfig {
     };
   }
 
+  /**
+   * A default NextJS page revalidation time.
+   * https://nextjs.org/docs/pages/building-your-application/data-fetching/incremental-static-regeneration#on-demand-revalidation
+   */
   static get defaultRevalidate() {
     const envValue = process.env.NEXT_PUBLIC_DEFAULT_ISR_REVALIDATE_SECONDS;
     const value = envValue ? parseEnvValue(envValue) : 60;
@@ -126,12 +198,14 @@ class AppConfig {
     return value;
   }
 
+  /** A feature flag for the similar events. */
   static get showSimilarEvents() {
     return Boolean(
       parseEnvValue(process.env.NEXT_PUBLIC_SHOW_SIMILAR_EVENTS, true)
     );
   }
 
+  /** A feature flag that can be used to show the enrolment status in the card details. */
   static get showEnrolmentStatusInCardDetails() {
     return Boolean(
       parseEnvValue(
@@ -141,6 +215,11 @@ class AppConfig {
     );
   }
 
+  /**
+   * A map of URL reqriting.
+   * Rewrite the URLs returned by the HEadless CMS
+   * so that they can be routed and used inside the app.
+   * */
   static get URLRewriteMapping() {
     return {
       [AppConfig.linkedEventsEventEndpoint]: ROUTES.EVENTS.replace(

apps/hobbies-helsinki/README.md

@@ -98,15 +98,15 @@ Hobbies uses a lot of the components from the HCRC-lib. For example the article
 
 There are 2 Apollo-clients in implemented: an Apollo-client for _`Headless CMS` to fetch articles and dynamic pages_ from the CMS and an Apollo-client for _`LinkedEvents` to fetch events_ from the Event-proxy. They both contains URL-fields that are targeted to an external source. Since the content is wanted to be rendered inside the Hobbies app, the URLs needs to be transformed so that they are pointing to an internal path. An Apollo Link is a create place to do the transformation, when the URL context is known. Therefore, the URL should include a hint of the context, e.g a context path like `/articles*` or `/pages*` or a domain e.g `linkedvents.hel.fi`.
 
-The transformation table is in the `AppConfig.ts`:
+The transformation table is in the [AppConfig.ts](./src/domain/app/AppConfig.ts) :
 
 ```typescript
 class AppConfig {
   // ...
   static get linkedEventsEventEndpoint() {
     return getEnvOrError(
       publicRuntimeConfig.linkedEvents,
-      'LINKEDEVENTS_EVENT_ENDPOINT'
+      "LINKEDEVENTS_EVENT_ENDPOINT"
     );
   }
   static get cmsArticlesContextPath() {
@@ -131,6 +131,10 @@ class AppConfig {
 }
 ```
 
+## Application configuration
+
+The application configuration is done via the [AppConfig.ts](./src/domain/app/AppConfig.ts) as much as possible, so there would be a single point to configure it.
+
 ## Contact
 
 City of Helsinki Slack channel #hobbieshelsinki