config-loader: document the rest of the config sources

Signed-off-by: Patrik Oldsberg <poldsberg@gmail.com>

packages/config-loader/src/sources/EnvConfigSource.ts

@@ -19,12 +19,48 @@ import { assertError } from '@backstage/errors';
 import { JsonObject } from '@backstage/types';
 import { AsyncConfigSourceIterator, ConfigSource } from './types';
 
+/**
+ * Options for {@link EnvConfigSource.create}.
+ *
+ * @public
+ */
+export interface EnvConfigSourceOptions {
+  /**
+   * The environment variables to use, defaults to {@link process.env}.
+   */
+  env?: Record<string, string | undefined>;
+}
+
+/**
+ * A config source that reads configuration from the environment.
+ *
+ * @remarks
+ *
+ * Only environment variables prefixed with APP_CONFIG_ will be considered.
+ *
+ * For each variable, the prefix will be removed, and rest of the key will
+ * be split by '_'. Each part will then be used as keys to build up a nested
+ * config object structure. The treatment of the entire environment variable
+ * is case-sensitive.
+ *
+ * The value of the variable should be JSON serialized, as it will be parsed
+ * and the type will be kept intact. For example "true" and true are treated
+ * differently, as well as "42" and 42.
+ *
+ * For example, to set the config app.title to "My Title", use the following:
+ *
+ * APP_CONFIG_app_title='"My Title"'
+ *
+ * @public
+ */
 export class EnvConfigSource implements ConfigSource {
-  static create(options: {
-    env?: {
-      [name: string]: string | undefined;
-    };
-  }): ConfigSource {
+  /**
+   * Creates a new config source that reads from the environment.
+   *
+   * @param options - Options for the config source.
+   * @returns A new config source that reads from the environment.
+   */
+  static create(options: EnvConfigSourceOptions): ConfigSource {
     return new EnvConfigSource(options?.env ?? process.env);
   }
 
@@ -47,6 +83,8 @@ const CONFIG_KEY_PART_PATTERN = /^[a-z][a-z0-9]*(?:[-_][a-z][a-z0-9]*)*$/i;
 /**
  * Read runtime configuration from the environment.
  *
+ * @remarks
+ *
  * Only environment variables prefixed with APP_CONFIG_ will be considered.
  *
  * For each variable, the prefix will be removed, and rest of the key will

packages/config-loader/src/sources/FileConfigSource.ts

@@ -27,18 +27,39 @@ import {
 } from './types';
 import { createConfigTransformer } from './transform';
 
+/**
+ * Options for {@link FileConfigSource.create}.
+ *
+ * @public
+ */
 export interface FileConfigSourceOptions {
   /**
    * The path to the config file that should be loaded.
    */
   path: string;
+
   /**
-   * Function used to resolve environment variables.
+   * A substitution function to use instead of the default environment substitution.
    */
   substitutionFunc?: SubstitutionFunc;
 }
 
+/**
+ * A config source that loads configuration from a local file.
+ *
+ * @public
+ */
 export class FileConfigSource implements ConfigSource {
+  /**
+   * Creates a new config source that loads configuration from the given path.
+   *
+   * @remarks
+   *
+   * The source will watch the file for changes, as well as any referenced files.
+   *
+   * @param options - Options for the config source.
+   * @returns A new config source that loads from the given path.
+   */
   static create(options: FileConfigSourceOptions): ConfigSource {
     if (!isAbsolute(options.path)) {
       throw new Error(`Config load path is not absolute: '${options.path}'`);

packages/config-loader/src/sources/RemoteConfigSource.ts

@@ -29,13 +29,42 @@ import {
 
 const DEFAULT_RELOAD_INTERVAL_SECONDS = 60;
 
+/**
+ * Options for {@link RemoteConfigSource.create}.
+ *
+ * @public
+ */
 export interface RemoteConfigSourceOptions {
+  /**
+   * The URL to load the config from.
+   */
   url: string;
+
+  /**
+   * The interval in seconds to reload the config from the remote URL.
+   *
+   * Set to Infinity to disable reloading.
+   */
   reloadIntervalSeconds?: number;
+
+  /**
+   * A substitution function to use instead of the default environment substitution.
+   */
   substitutionFunc?: SubstitutionFunc;
 }
 
+/**
+ * A config source that loads configuration from a remote URL.
+ *
+ * @public
+ */
 export class RemoteConfigSource implements ConfigSource {
+  /**
+   * Creates a new {@link RemoteConfigSource}.
+   *
+   * @param options - Options for the source.
+   * @returns A new remote config source.
+   */
   static create(options: RemoteConfigSourceOptions): ConfigSource {
     try {
       // eslint-disable-next-line no-new

packages/config-loader/src/sources/StaticConfigSource.ts

@@ -22,6 +22,11 @@ import {
 } from './types';
 import { simpleDefer } from './utils';
 
+/**
+ * Options for {@link StaticConfigSource.create}.
+ *
+ * @public
+ */
 export interface StaticConfigSourceOptions {
   data:
     | JsonObject
@@ -81,7 +86,18 @@ function isAsyncIterable<T>(value: {}): value is AsyncIterable<T> {
   return Symbol.asyncIterator in value;
 }
 
+/**
+ * A configuration source that reads from a static object, promise, iterable, or observable.
+ *
+ * @public
+ */
 export class StaticConfigSource implements ConfigSource {
+  /**
+   * Creates a new {@link StaticConfigSource}.
+   *
+   * @param options - Options for the config source
+   * @returns A new static config source
+   */
   static create(options: StaticConfigSourceOptions): ConfigSource {
     const { data, context = 'static-config' } = options;
     if (!data) {