Add public tags and documentation in the error and config-loader packages

Part of #7688

Signed-off-by: Fredrik Adelöw <freben@gmail.com>

.changeset/moody-bats-matter.md

@@ -0,0 +1,5 @@
+---
+'@backstage/config-loader': minor
+---
+
+Removed the `EnvFunc` public export. Its only usage was to be passed in to `LoadConfigOptions.experimentalEnvFunc`. If you were using this type, add a definition in your own project instead with the signature `(name: string) => Promise<string | undefined>`.

.changeset/quick-frogs-double.md

@@ -0,0 +1,6 @@
+---
+'@backstage/config-loader': patch
+'@backstage/errors': patch
+---
+
+Add public tags and documentation

packages/config-loader/api-report.md

@@ -26,18 +26,15 @@ export type ConfigSchemaProcessingOptions = {
 // @public
 export type ConfigVisibility = 'frontend' | 'backend' | 'secret';
 
-// @public (undocumented)
-export type EnvFunc = (name: string) => Promise<string | undefined>;
-
 // @public
 export function loadConfig(options: LoadConfigOptions): Promise<AppConfig[]>;
 
-// @public (undocumented)
+// @public
 export type LoadConfigOptions = {
   configRoot: string;
   configPaths: string[];
   env?: string;
-  experimentalEnvFunc?: EnvFunc;
+  experimentalEnvFunc?: (name: string) => Promise<string | undefined>;
   watch?: {
     onChange: (configs: AppConfig[]) => void;
     stopSignal?: Promise<void>;
@@ -49,7 +46,7 @@ export function loadConfigSchema(
   options: LoadConfigSchemaOptions,
 ): Promise<ConfigSchema>;
 
-// @public (undocumented)
+// @public
 export type LoadConfigSchemaOptions =
   | {
       dependencies: string[];

packages/config-loader/src/index.ts

@@ -25,7 +25,6 @@ export type {
   ConfigSchema,
   ConfigSchemaProcessingOptions,
   ConfigVisibility,
-  EnvFunc,
   LoadConfigSchemaOptions,
   TransformFunc,
 } from './lib';

packages/config-loader/src/lib/schema/load.ts

@@ -25,7 +25,11 @@ import {
   CONFIG_VISIBILITIES,
 } from './types';
 
-/** @public */
+/**
+ * Options that control the loading of configuration schema files in the backend.
+ *
+ * @public
+ */
 export type LoadConfigSchemaOptions =
   | {
       dependencies: string[];

packages/config-loader/src/lib/transform/index.ts

@@ -17,4 +17,3 @@
 export { applyConfigTransforms } from './apply';
 export { createIncludeTransform } from './include';
 export { createSubstitutionTransform } from './substitution';
-export type { EnvFunc } from './types';

packages/config-loader/src/lib/transform/types.ts

@@ -16,7 +16,6 @@
 
 import { JsonValue } from '@backstage/config';
 
-/** @public */
 export type EnvFunc = (name: string) => Promise<string | undefined>;
 
 export type ReadFileFunc = (path: string) => Promise<string>;

packages/config-loader/src/loader.ts

@@ -26,9 +26,12 @@ import {
   createIncludeTransform,
   createSubstitutionTransform,
 } from './lib';
-import { EnvFunc } from './lib/transform/types';
 
-/** @public */
+/**
+ * Options that control the loading of configuration files in the backend.
+ *
+ * @public
+ */
 export type LoadConfigOptions = {
   // The root directory of the config loading context. Used to find default configs.
   configRoot: string;
@@ -44,7 +47,7 @@ export type LoadConfigOptions = {
    *
    * @experimental This API is not stable and may change at any point
    */
-  experimentalEnvFunc?: EnvFunc;
+  experimentalEnvFunc?: (name: string) => Promise<string | undefined>;
 
   /**
    * An optional configuration that enables watching of config files.

packages/errors/api-report.md

@@ -14,7 +14,7 @@ export class AuthenticationError extends CustomErrorBase {}
 // @public
 export class ConflictError extends CustomErrorBase {}
 
-// @public (undocumented)
+// @public
 export class CustomErrorBase extends Error {
   constructor(message?: string, cause?: Error | unknown);
   // (undocumented)

packages/errors/src/errors/CustomErrorBase.ts

@@ -16,7 +16,21 @@
 
 import { isError } from './assertion';
 
-/** @public */
+/**
+ * A base class that custom Error classes can inherit from.
+ *
+ * @public
+ * @example
+ *```ts
+ * class MyCustomError extends CustomErrorBase {}
+ *
+ * const e = new MyCustomError('Some message', cause);
+ * // e.name === 'MyCustomError'
+ * // e.message === 'Some message'
+ * // e.cause === cause
+ * // e.stack is set if the runtime supports it
+ * ```
+ */
 export class CustomErrorBase extends Error {
   readonly cause?: Error;