config: document interface and mark types as public

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

.changeset/great-balloons-walk.md

@@ -0,0 +1,5 @@
+---
+'@backstage/config': patch
+---
+
+Documented `Config` interface and mark types as public.

packages/config/api-report.md

@@ -3,18 +3,14 @@
 > Do not edit this file. It is a report generated by [API Extractor](https://api-extractor.com/).
 
 ```ts
-// Warning: (ae-missing-release-tag) "AppConfig" is exported by the package, but it is missing a release tag (@alpha, @beta, @public, or @internal)
-//
-// @public (undocumented)
+// @public
 export type AppConfig = {
   context: string;
   data: JsonObject;
   filteredKeys?: string[];
 };
 
-// Warning: (ae-missing-release-tag) "Config" is exported by the package, but it is missing a release tag (@alpha, @beta, @public, or @internal)
-//
-// @public (undocumented)
+// @public
 export type Config = {
   subscribe?(onChange: () => void): {
     unsubscribe: () => void;
@@ -37,9 +33,7 @@ export type Config = {
   getOptionalStringArray(key: string): string[] | undefined;
 };
 
-// Warning: (ae-missing-release-tag) "ConfigReader" is exported by the package, but it is missing a release tag (@alpha, @beta, @public, or @internal)
-//
-// @public (undocumented)
+// @public
 export class ConfigReader implements Config {
   constructor(
     data: JsonObject | undefined,
@@ -83,26 +77,18 @@ export class ConfigReader implements Config {
   keys(): string[];
 }
 
-// Warning: (ae-missing-release-tag) "JsonArray" is exported by the package, but it is missing a release tag (@alpha, @beta, @public, or @internal)
-//
-// @public (undocumented)
+// @public
 export interface JsonArray extends Array<JsonValue> {}
 
-// Warning: (ae-missing-release-tag) "JsonObject" is exported by the package, but it is missing a release tag (@alpha, @beta, @public, or @internal)
-//
-// @public (undocumented)
+// @public
 export type JsonObject = {
   [key in string]?: JsonValue;
 };
 
-// Warning: (ae-missing-release-tag) "JsonPrimitive" is exported by the package, but it is missing a release tag (@alpha, @beta, @public, or @internal)
-//
-// @public (undocumented)
+// @public
 export type JsonPrimitive = number | string | boolean | null;
 
-// Warning: (ae-missing-release-tag) "JsonValue" is exported by the package, but it is missing a release tag (@alpha, @beta, @public, or @internal)
-//
-// @public (undocumented)
+// @public
 export type JsonValue = JsonObject | JsonArray | JsonPrimitive;
 
 // (No @packageDocumentation comment for this package)

packages/config/src/reader.ts

@@ -54,6 +54,12 @@ const errors = {
   },
 };
 
+/**
+ * An implementation of the `Config` interface that uses a plain JavaScript object
+ * for the backing data, with the ability of linking multiple readers together.
+ *
+ * @public
+ */
 export class ConfigReader implements Config {
   /**
    * A set of key paths that where removed from the config due to not being visible.

packages/config/src/types.ts

@@ -14,17 +14,61 @@
  * limitations under the License.
  */
 
+/**
+ * A type representing all allowed JSON primitive values.
+ *
+ * @public
+ */
 export type JsonPrimitive = number | string | boolean | null;
+
+/**
+ * A type representing all allowed JSON object values.
+ *
+ * @public
+ */
 export type JsonObject = { [key in string]?: JsonValue };
+
+/**
+ * A type representing all allowed JSON array values.
+ *
+ * @public
+ */
 export interface JsonArray extends Array<JsonValue> {}
+
+/**
+ * A type representing all allowed JSON values.
+ *
+ * @public
+ */
 export type JsonValue = JsonObject | JsonArray | JsonPrimitive;
 
+/**
+ * A serialized form of configuration data that carries additional context.
+ *
+ * @public
+ */
 export type AppConfig = {
+  /**
+   * A string representing the source of this configuration data, for example a filepath.
+   */
   context: string;
+  /**
+   * The configuration data itself.
+   */
   data: JsonObject;
+  /**
+   * A list of keys that where filtered out from the configuration when it was loaded.
+   *
+   * This can be used to warn the user if they try to read any of these keys.
+   */
   filteredKeys?: string[];
 };
 
+/**
+ * The interface used to represent static configuration at runtime.
+ *
+ * @public
+ */
 export type Config = {
   /**
    * Subscribes to the configuration object in order to receive a notification
@@ -37,28 +81,90 @@ export type Config = {
     unsubscribe: () => void;
   };
 
+  /**
+   * Checks whether the given key is present.
+   */
   has(key: string): boolean;
 
+  /**
+   * Lists all available configuration keys.
+   */
   keys(): string[];
 
+  /**
+   * Same as `getOptional`, but will throw an error if there's no value for the given key.
+   */
   get<T = JsonValue>(key?: string): T;
+
+  /**
+   * Read out all configuration data for the given key.
+   *
+   * Usage of this method should be avoided as the typed alternatives provide
+   * much better error reporting. The main use-case of this method is to determine
+   * the type of a configuration value in the case where there are multiple possible
+   * shapes of the configuration.
+   */
   getOptional<T = JsonValue>(key?: string): T | undefined;
 
+  /**
+   * Same as `getOptionalConfig`, but will throw an error if there's no value for the given key.
+   */
   getConfig(key: string): Config;
+
+  /**
+   * Creates a sub-view of the configuration object.
+   * The configuration value at the position of the provided key must be an object.
+   */
   getOptionalConfig(key: string): Config | undefined;
 
+  /**
+   * Same as `getOptionalConfigArray`, but will throw an error if there's no value for the given key.
+   */
   getConfigArray(key: string): Config[];
+
+  /**
+   * Creates a sub-view of an array of configuration objects.
+   * The configuration value at the position of the provided key must be an array of objects.
+   */
   getOptionalConfigArray(key: string): Config[] | undefined;
 
+  /**
+   * Same as `getOptionalNumber`, but will throw an error if there's no value for the given key.
+   */
   getNumber(key: string): number;
+
+  /**
+   * Reads a configuration value at the given key, expecting it to be a number.
+   */
   getOptionalNumber(key: string): number | undefined;
 
+  /**
+   * Same as `getOptionalBoolean`, but will throw an error if there's no value for the given key.
+   */
   getBoolean(key: string): boolean;
+
+  /**
+   * Reads a configuration value at the given key, expecting it to be a boolean.
+   */
   getOptionalBoolean(key: string): boolean | undefined;
 
+  /**
+   * Same as `getOptionalString`, but will throw an error if there's no value for the given key.
+   */
   getString(key: string): string;
+
+  /**
+   * Reads a configuration value at the given key, expecting it to be a string.
+   */
   getOptionalString(key: string): string | undefined;
 
+  /**
+   * Same as `getOptionalStringArray`, but will throw an error if there's no value for the given key.
+   */
   getStringArray(key: string): string[];
+
+  /**
+   * Reads a configuration value at the given key, expecting it to be an array of strings.
+   */
   getOptionalStringArray(key: string): string[] | undefined;
 };