From aaee88b0af239604a4dc897b755e79fb5ed1b835 Mon Sep 17 00:00:00 2001
From: Patrik Oldsberg <poldsberg@gmail.com>
Date: Fri, 31 Mar 2023 12:01:36 +0200
Subject: [PATCH] config-loader: document source types

Signed-off-by: Patrik Oldsberg <poldsberg@gmail.com>
---
 packages/config-loader/src/sources/types.ts | 51 +++++++++++++++++++++
 1 file changed, 51 insertions(+)

diff --git a/packages/config-loader/src/sources/types.ts b/packages/config-loader/src/sources/types.ts
index 035fbd8de8..626a2a63f3 100644
--- a/packages/config-loader/src/sources/types.ts
+++ b/packages/config-loader/src/sources/types.ts
@@ -16,6 +16,11 @@
 
 import { AppConfig } from '@backstage/config';
 
+/**
+ * The data returned by {@link ConfigSource.readConfigData}.
+ *
+ * @public
+ */
 export interface ConfigSourceData extends AppConfig {
   /**
    * The file path that this configuration was loaded from, if it was loaded from a file.
@@ -23,10 +28,20 @@ export interface ConfigSourceData extends AppConfig {
   path?: string;
 }
 
+/**
+ * Options for {@link ConfigSource.readConfigData}.
+ *
+ * @public
+ */
 export interface ReadConfigDataOptions {
   signal?: AbortSignal;
 }
 
+/**
+ * The type of the iterator returned by {@link ConfigSource.readConfigData}.
+ *
+ * @public
+ */
 export interface AsyncConfigSourceIterator
   extends AsyncIterator<{ data: ConfigSourceData[] }, void, void> {
   [Symbol.asyncIterator](): AsyncIterator<
@@ -36,8 +51,44 @@ export interface AsyncConfigSourceIterator
   >;
 }
 
+/**
+ * A source of configuration data.
+ *
+ * @remarks
+ *
+ * It is recommended to implement the `readConfigData` method as an async generator.
+ *
+ * @example
+ *
+ * ```ts
+ * class MyConfigSource implements ConfigSource {
+ *   async *readConfigData() {
+ *     yield {
+ *       data: [{
+ *         context: 'example',
+ *         data: { backend: { baseUrl: 'http://localhost' } }
+ *       }]
+ *     };
+ *   }
+ * }
+ * ```
+ *
+ * @public
+ */
 export interface ConfigSource {
   readConfigData(options?: ReadConfigDataOptions): AsyncConfigSourceIterator;
 }
 
+/**
+ * A custom function to be used for substitution withing configuration files.
+ *
+ * @remarks
+ *
+ * Substitutions use the following syntax: `baseUrl: https://${HOSTNAME}`, where
+ * `'HOSTNAME'` is the name of the variable to be substituted.
+ *
+ * The default substitution function will read the value of the environment.
+ *
+ * @public
+ */
 export type SubstitutionFunc = (name: string) => Promise<string | undefined>;