Merge pull request #8824 from backstage/freben/api-commonz

🧹  Clean up API reports in backend-common

.changeset/twelve-panthers-move.md

@@ -0,0 +1,5 @@
+---
+'@backstage/backend-common': patch
+---
+
+Clean up API reports

packages/backend-common/api-report.md

@@ -34,9 +34,7 @@ import { Server } from 'http';
 import * as winston from 'winston';
 import { Writable } from 'stream';
 
-// Warning: (ae-missing-release-tag) "AwsS3UrlReader" is exported by the package, but it is missing a release tag (@alpha, @beta, @public, or @internal)
-//
-// @public (undocumented)
+// @public
 export class AwsS3UrlReader implements UrlReader {
   constructor(
     integration: AwsS3Integration,
@@ -59,7 +57,7 @@ export class AwsS3UrlReader implements UrlReader {
   toString(): string;
 }
 
-// @public (undocumented)
+// @public
 export class AzureUrlReader implements UrlReader {
   constructor(
     integration: AzureIntegration,
@@ -114,12 +112,12 @@ export interface CacheClient {
   ): Promise<void>;
 }
 
-// @public (undocumented)
+// @public
 export type CacheClientOptions = {
   defaultTtl?: number;
 };
 
-// @public (undocumented)
+// @public
 export type CacheClientSetOptions = {
   ttl?: number;
 };
@@ -133,18 +131,17 @@ export class CacheManager {
   ): CacheManager;
 }
 
-// @public (undocumented)
+// @public
 export type CacheManagerOptions = {
   logger?: Logger_2;
   onError?: (err: Error) => void;
 };
 
-// @public (undocumented)
+// @public
 export const coloredFormat: winston.Logform.Format;
 
-// @public (undocumented)
+// @public
 export interface ContainerRunner {
-  // (undocumented)
   runContainer(opts: RunContainerOptions): Promise<void>;
 }
 
@@ -157,7 +154,7 @@ export function createDatabaseClient(
   overrides?: Partial<Knex.Config>,
 ): Knex<any, unknown[]>;
 
-// @public (undocumented)
+// @public
 export function createRootLogger(
   options?: winston.LoggerOptions,
   env?: NodeJS.ProcessEnv,
@@ -166,14 +163,14 @@ export function createRootLogger(
 // @public
 export function createServiceBuilder(_module: NodeModule): ServiceBuilder;
 
-// @public (undocumented)
+// @public
 export function createStatusCheckRouter(options: {
   logger: Logger_2;
   path?: string;
   statusCheck?: StatusCheck;
 }): Promise<express.Router>;
 
-// @public (undocumented)
+// @public
 export class DatabaseManager {
   forPlugin(pluginId: string): PluginDatabaseManager;
   static fromConfig(
@@ -187,7 +184,7 @@ export type DatabaseManagerOptions = {
   migrations?: PluginDatabaseManager['migrations'];
 };
 
-// @public (undocumented)
+// @public
 export class DockerContainerRunner implements ContainerRunner {
   constructor(options: { dockerClient: Docker });
   // (undocumented)
@@ -205,7 +202,7 @@ export function errorHandler(
   options?: ErrorHandlerOptions,
 ): ErrorRequestHandler;
 
-// @public (undocumented)
+// @public
 export type ErrorHandlerOptions = {
   showStackTraces?: boolean;
   logger?: Logger_2;
@@ -218,13 +215,13 @@ export type FromReadableArrayOptions = Array<{
   path: string;
 }>;
 
-// @public (undocumented)
+// @public
 export function getRootLogger(): winston.Logger;
 
 // @public
 export function getVoidLogger(): winston.Logger;
 
-// @public (undocumented)
+// @public
 export class Git {
   // (undocumented)
   add(options: { dir: string; filepath: string }): Promise<void>;
@@ -310,7 +307,7 @@ export class GithubUrlReader implements UrlReader {
   toString(): string;
 }
 
-// @public (undocumented)
+// @public
 export class GitlabUrlReader implements UrlReader {
   constructor(
     integration: GitLabIntegration,
@@ -398,7 +395,7 @@ export type ReadTreeResponseDirOptions = {
   targetDir?: string;
 };
 
-// @public (undocumented)
+// @public
 export interface ReadTreeResponseFactory {
   // (undocumented)
   fromReadableArray(
@@ -448,7 +445,7 @@ export type ReadUrlResponse = {
 // @public
 export function requestLoggingHandler(logger?: Logger_2): RequestHandler;
 
-// @public (undocumented)
+// @public
 export type RequestLoggingHandlerFactory = (
   logger?: Logger_2,
 ) => RequestHandler;
@@ -459,7 +456,7 @@ export function resolvePackagePath(name: string, ...paths: string[]): string;
 // @public
 export function resolveSafeChildPath(base: string, path: string): string;
 
-// @public (undocumented)
+// @public
 export type RunContainerOptions = {
   imageName: string;
   command?: string | string[];
@@ -508,7 +505,7 @@ export class ServerTokenManager implements TokenManager {
   static noop(): TokenManager;
 }
 
-// @public (undocumented)
+// @public
 export type ServiceBuilder = {
   loadConfig(config: Config): ServiceBuilder;
   setPort(port: number): ServiceBuilder;
@@ -534,7 +531,7 @@ export type ServiceBuilder = {
   start(): Promise<Server>;
 };
 
-// @public (undocumented)
+// @public
 export function setRootLogger(newLogger: winston.Logger): void;
 
 // @public @deprecated
@@ -554,7 +551,7 @@ export class SingleHostDiscovery implements PluginEndpointDiscovery {
   getExternalBaseUrl(pluginId: string): Promise<string>;
 }
 
-// @public (undocumented)
+// @public
 export type StatusCheck = () => Promise<any>;
 
 // @public
@@ -562,7 +559,7 @@ export function statusCheckHandler(
   options?: StatusCheckHandlerOptions,
 ): Promise<RequestHandler>;
 
-// @public (undocumented)
+// @public
 export interface StatusCheckHandlerOptions {
   statusCheck?: StatusCheck;
 }
@@ -597,7 +594,7 @@ export class UrlReaders {
   static default(options: UrlReadersOptions): UrlReader;
 }
 
-// @public (undocumented)
+// @public
 export type UrlReadersOptions = {
   config: Config;
   logger: Logger_2;
@@ -612,8 +609,4 @@ export function useHotCleanup(
 
 // @public
 export function useHotMemoize<T>(_module: NodeModule, valueFactory: () => T): T;
-
-// Warnings were encountered during analysis:
-//
-// src/database/types.d.ts:23:12 - (tsdoc-undefined-tag) The TSDoc tag "@default" is not defined in this configuration
 ```

packages/backend-common/src/cache/CacheClient.ts

@@ -22,7 +22,11 @@ type CacheClientArgs = {
   client: Keyv;
 };
 
-/** @public */
+/**
+ * Options passed to {@link CacheClient.set}.
+ *
+ * @public
+ */
 export type CacheClientSetOptions = {
   /**
    * Optional TTL in milliseconds. Defaults to the TTL provided when the client

packages/backend-common/src/cache/CacheManager.ts

@@ -55,8 +55,8 @@ export class CacheManager {
   private readonly errorHandler: CacheManagerOptions['onError'];
 
   /**
-   * Creates a new CacheManager instance by reading from the `backend` config
-   * section, specifically the `.cache` key.
+   * Creates a new {@link CacheManager} instance by reading from the `backend`
+   * config section, specifically the `.cache` key.
    *
    * @param config - The loaded application configuration.
    */
@@ -93,7 +93,8 @@ export class CacheManager {
   /**
    * Generates a PluginCacheManager for consumption by plugins.
    *
-   * @param pluginId - The plugin that the cache manager should be created for. Plugin names should be unique.
+   * @param pluginId - The plugin that the cache manager should be created for.
+   *        Plugin names should be unique.
    */
   forPlugin(pluginId: string): PluginCacheManager {
     return {

packages/backend-common/src/cache/types.ts

@@ -17,7 +17,11 @@
 import { Logger } from 'winston';
 import { CacheClient } from './CacheClient';
 
-/** @public */
+/**
+ * Options given when constructing a {@link CacheClient}.
+ *
+ * @public
+ */
 export type CacheClientOptions = {
   /**
    * An optional default TTL (in milliseconds) to be set when getting a client
@@ -27,7 +31,11 @@ export type CacheClientOptions = {
   defaultTtl?: number;
 };
 
-/** @public */
+/**
+ * Options given when constructing a {@link CacheManager}.
+ *
+ * @public
+ */
 export type CacheManagerOptions = {
   /**
    * An optional logger for use by the PluginCacheManager.
@@ -42,17 +50,19 @@ export type CacheManagerOptions = {
 };
 
 /**
- * The PluginCacheManager manages access to cache stores that Plugins get.
+ * Manages access to cache stores that plugins get.
  *
  * @public
  */
 export type PluginCacheManager = {
   /**
-   * getClient provides backend plugins cache connections for itself.
+   * Provides backend plugins cache connections for themselves.
    *
-   * The purpose of this method is to allow plugins to get isolated data
-   * stores so that plugins are discouraged from cache-level integration
-   * and/or cache key collisions.
+   * @remarks
+   *
+   * The purpose of this method is to allow plugins to get isolated data stores
+   * so that plugins are discouraged from cache-level integration and/or cache
+   * key collisions.
    */
   getClient: (options?: CacheClientOptions) => CacheClient;
 };

packages/backend-common/src/database/DatabaseManager.ts

@@ -38,7 +38,7 @@ function pluginPath(pluginId: string): string {
 }
 
 /**
- * Configuration options object.
+ * Creation options for {@link DatabaseManager}.
  *
  * @public
  */
@@ -46,15 +46,20 @@ export type DatabaseManagerOptions = {
   migrations?: PluginDatabaseManager['migrations'];
 };
 
-/** @public */
+/**
+ * Manages database connections for Backstage backend plugins.
+ *
+ * The database manager allows the user to set connection and client settings on
+ * a per pluginId basis by defining a database config block under
+ * `plugin.<pluginId>` in addition to top level defaults. Optionally, a user may
+ * set `prefix` which is used to prefix generated database names if config is
+ * not provided.
+ *
+ * @public
+ */
 export class DatabaseManager {
   /**
-   * Creates a DatabaseManager from `backend.database` config.
-   *
-   * The database manager allows the user to set connection and client settings on a per pluginId
-   * basis by defining a database config block under `plugin.<pluginId>` in addition to top level
-   * defaults. Optionally, a user may set `prefix` which is used to prefix generated database
-   * names if config is not provided.
+   * Creates a {@link DatabaseManager} from `backend.database` config.
    *
    * @param config - The loaded application configuration.
    * @param options - An optional configuration object.
@@ -108,7 +113,7 @@ export class DatabaseManager {
    * which is the pluginId prefixed with 'backstage_plugin_'. If `pluginDivisionMode` is
    * `schema`, it will fallback to using the default database for the knex instance.
    *
-   * @param pluginId Lookup the database name for given plugin
+   * @param pluginId - Lookup the database name for given plugin
    * @returns String representing the plugin's database name
    */
   private getDatabaseName(pluginId: string): string | undefined {
@@ -143,12 +148,13 @@ export class DatabaseManager {
   /**
    * Provides the client type which should be used for a given plugin.
    *
-   * The client type is determined by plugin specific config if present. Otherwise the base
-   * client is used as the fallback.
+   * The client type is determined by plugin specific config if present.
+   * Otherwise the base client is used as the fallback.
    *
-   * @param pluginId Plugin to get the client type for
-   * @returns Object with client type returned as `client` and boolean representing whether
-   * or not the client was overridden as `overridden`
+   * @param pluginId - Plugin to get the client type for
+   * @returns Object with client type returned as `client` and boolean
+   *          representing whether or not the client was overridden as
+   *          `overridden`
    */
   private getClientType(pluginId: string): {
     client: string;
@@ -169,8 +175,8 @@ export class DatabaseManager {
   /**
    * Provides the knexConfig which should be used for a given plugin.
    *
-   * @param pluginId Plugin to get the knexConfig for
-   * @returns the merged kexConfig value or undefined if it isn't specified
+   * @param pluginId - Plugin to get the knexConfig for
+   * @returns The merged knexConfig value or undefined if it isn't specified
    */
   private getAdditionalKnexConfig(pluginId: string): JsonObject | undefined {
     const pluginConfig = this.config
@@ -197,13 +203,15 @@ export class DatabaseManager {
   }
 
   /**
-   * Provides a Knex connection plugin config by combining base and plugin config.
+   * Provides a Knex connection plugin config by combining base and plugin
+   * config.
    *
-   * This method provides a baseConfig for a plugin database connector. If the client type
-   * has not been overridden, the global connection config will be included with plugin
-   * specific config as the base. Values from the plugin connection take precedence over the
-   * base. Base database name is omitted for all supported databases excluding SQLite unless
-   * `pluginDivisionMode` is set to `schema`.
+   * This method provides a baseConfig for a plugin database connector. If the
+   * client type has not been overridden, the global connection config will be
+   * included with plugin specific config as the base. Values from the plugin
+   * connection take precedence over the base. Base database name is omitted for
+   * all supported databases excluding SQLite unless `pluginDivisionMode` is set
+   * to `schema`.
    */
   private getConnectionConfig(
     pluginId: string,
@@ -249,9 +257,10 @@ export class DatabaseManager {
   /**
    * Provides a Knex database config for a given plugin.
    *
-   * This method provides a Knex configuration object along with the plugin's client type.
+   * This method provides a Knex configuration object along with the plugin's
+   * client type.
    *
-   * @param pluginId The plugin that the database config should correspond with
+   * @param pluginId - The plugin that the database config should correspond with
    */
   private getConfigForPlugin(pluginId: string): Knex.Config {
     const { client } = this.getClientType(pluginId);
@@ -264,20 +273,21 @@ export class DatabaseManager {
   }
 
   /**
-   * Provides a partial Knex.Config database schema override for a given plugin.
+   * Provides a partial `Knex.Config` database schema override for a given
+   * plugin.
    *
-   * @param pluginId Target plugin to get database schema override
-   * @returns Partial Knex.Config with database schema override
+   * @param pluginId - Target plugin to get database schema override
+   * @returns Partial `Knex.Config` with database schema override
    */
   private getSchemaOverrides(pluginId: string): Knex.Config | undefined {
     return createSchemaOverride(this.getClientType(pluginId).client, pluginId);
   }
 
   /**
-   * Provides a partial Knex.Config database name override for a given plugin.
+   * Provides a partial `Knex.Config`• database name override for a given plugin.
    *
-   * @param pluginId Target plugin to get database name override
-   * @returns Partial Knex.Config with database name override
+   * @param pluginId - Target plugin to get database name override
+   * @returns Partial `Knex.Config` with database name override
    */
   private getDatabaseOverrides(pluginId: string): Knex.Config {
     const databaseName = this.getDatabaseName(pluginId);
@@ -289,8 +299,9 @@ export class DatabaseManager {
   /**
    * Provides a scoped Knex client for a plugin as per application config.
    *
-   *  @param pluginId Plugin to get a Knex client for
-   *  @returns Promise which resolves to a scoped Knex database client for a plugin
+   * @param pluginId - Plugin to get a Knex client for
+   * @returns Promise which resolves to a scoped Knex database client for a
+   *          plugin
    */
   private async getDatabase(pluginId: string): Promise<Knex> {
     const pluginConfig = new ConfigReader(

packages/backend-common/src/database/connection.ts

@@ -58,7 +58,7 @@ export function createDatabaseClient(
 }
 
 /**
- * Alias for createDatabaseClient
+ * Alias for {@link createDatabaseClient}
  *
  * @public
  * @deprecated Use createDatabaseClient instead
@@ -100,7 +100,8 @@ export async function ensureSchemaExists(
 }
 
 /**
- * Provides a Knex.Config object with the provided database name for a given client.
+ * Provides a `Knex.Config` object with the provided database name for a given
+ * client.
  */
 export function createNameOverride(
   client: string,
@@ -117,7 +118,8 @@ export function createNameOverride(
 }
 
 /**
- * Provides a Knex.Config object with the provided database schema for a given client. Currently only supported by `pg`.
+ * Provides a `Knex.Config` object with the provided database schema for a given
+ * client. Currently only supported by `pg`.
  */
 export function createSchemaOverride(
   client: string,
@@ -156,7 +158,8 @@ export function parseConnectionString(
 }
 
 /**
- * Normalizes a connection config or string into an object which can be passed to Knex.
+ * Normalizes a connection config or string into an object which can be passed
+ * to Knex.
  */
 export function normalizeConnection(
   connection: Knex.StaticConnectionConfig | JsonObject | string | undefined,

packages/backend-common/src/database/types.ts

@@ -38,7 +38,7 @@ export interface PluginDatabaseManager {
     /**
      * skip database migrations. Useful if connecting to a read-only database.
      *
-     * @default false
+     * @defaultValue false
      */
     skip?: boolean;
   };

packages/backend-common/src/logging/formats.ts

@@ -31,7 +31,11 @@ const coloredTemplate = (info: TransformableInfo) => {
   return `${timestampColor} ${prefixColor} ${level} ${message} ${extraFields}`;
 };
 
-/** @public */
+/**
+ * A logging format that adds coloring to console output.
+ *
+ * @public
+ */
 export const coloredFormat = winston.format.combine(
   winston.format.timestamp(),
   winston.format.colorize({

packages/backend-common/src/logging/rootLogger.ts

@@ -23,12 +23,29 @@ import { escapeRegExp } from '../util/escapeRegExp';
 let rootLogger: winston.Logger;
 let redactionRegExp: RegExp | undefined;
 
-/** @public */
+/**
+ * Gets the current root logger.
+ *
+ * @public
+ */
 export function getRootLogger(): winston.Logger {
   return rootLogger;
 }
 
-/** @public */
+/**
+ * Sets a completely custom default "root" logger.
+ *
+ * @remarks
+ *
+ * This is the logger instance that will be the foundation for all other logger
+ * instances passed to plugins etc, in a given backend.
+ *
+ * Only use this if you absolutely need to make a completely custom logger.
+ * Normally if you want to make light adaptations to the default logger
+ * behavior, you would instead call {@link createRootLogger}.
+ *
+ * @public
+ */
 export function setRootLogger(newLogger: winston.Logger) {
   rootLogger = newLogger;
 }
@@ -67,7 +84,17 @@ function redactLogLine(info: winston.Logform.TransformableInfo) {
   return info;
 }
 
-/** @public */
+/**
+ * Creates a default "root" logger. This also calls {@link setRootLogger} under
+ * the hood.
+ *
+ * @remarks
+ *
+ * This is the logger instance that will be the foundation for all other logger
+ * instances passed to plugins etc, in a given backend.
+ *
+ * @public
+ */
 export function createRootLogger(
   options: winston.LoggerOptions = {},
   env = process.env,

packages/backend-common/src/middleware/errorHandler.ts

@@ -28,7 +28,11 @@ import { ErrorRequestHandler, NextFunction, Request, Response } from 'express';
 import { Logger } from 'winston';
 import { getRootLogger } from '../logging';
 
-/** @public */
+/**
+ * Options passed to the {@link errorHandler} middleware.
+ *
+ * @public
+ */
 export type ErrorHandlerOptions = {
   /**
    * Whether error response bodies should show error stack traces or not.

packages/backend-common/src/middleware/statusCheckHandler.ts

@@ -16,10 +16,19 @@
 
 import { NextFunction, Request, Response, RequestHandler } from 'express';
 
-/** @public */
+/**
+ * A custom status checking function, passed to {@link statusCheckHandler} and
+ * {@link createStatusCheckRouter}.
+ *
+ * @public
+ */
 export type StatusCheck = () => Promise<any>;
 
-/** @public */
+/**
+ * Options passed to {@link statusCheckHandler}.
+ *
+ * @public
+ */
 export interface StatusCheckHandlerOptions {
   /**
    * Optional status function which returns a message.

packages/backend-common/src/reading/AwsS3UrlReader.ts

@@ -94,6 +94,11 @@ const parseURL = (
   };
 };
 
+/**
+ * Implements a {@link UrlReader} for AWS S3 buckets.
+ *
+ * @public
+ */
 export class AwsS3UrlReader implements UrlReader {
   static factory: ReaderFactory = ({ config, treeResponseFactory }) => {
     const integrations = ScmIntegrations.fromConfig(config);

packages/backend-common/src/reading/AzureUrlReader.ts

@@ -38,7 +38,11 @@ import {
   ReadUrlResponse,
 } from './types';
 
-/** @public */
+/**
+ * Implements a {@link UrlReader} for Azure repos.
+ *
+ * @public
+ */
 export class AzureUrlReader implements UrlReader {
   static factory: ReaderFactory = ({ config, treeResponseFactory }) => {
     const integrations = ScmIntegrations.fromConfig(config);

packages/backend-common/src/reading/BitbucketUrlReader.ts

@@ -41,8 +41,8 @@ import {
 } from './types';
 
 /**
- * A processor that adds the ability to read files from Bitbucket v1 and v2 APIs, such as
- * the one exposed by Bitbucket Cloud itself.
+ * Implements a {@link UrlReader} for files from Bitbucket v1 and v2 APIs, such
+ * as the one exposed by Bitbucket Cloud itself.
  *
  * @public
  */

packages/backend-common/src/reading/FetchUrlReader.ts

@@ -27,7 +27,7 @@ import {
 import path from 'path';
 
 /**
- * A UrlReader that does a plain fetch of the URL.
+ * A {@link UrlReader} that does a plain fetch of the URL.
  *
  * @public
  */

packages/backend-common/src/reading/GithubUrlReader.ts

@@ -50,7 +50,7 @@ export type GhBlobResponse =
   RestEndpointMethodTypes['git']['getBlob']['response']['data'];
 
 /**
- * A processor that adds the ability to read files from GitHub v3 APIs, such as
+ * Implements a {@link UrlReader} for files through the GitHub v3 APIs, such as
  * the one exposed by GitHub itself.
  *
  * @public

packages/backend-common/src/reading/GitlabUrlReader.ts

@@ -39,7 +39,11 @@ import {
 } from './types';
 import { trimEnd } from 'lodash';
 
-/** @public */
+/**
+ * Implements a {@link UrlReader} for files on GitLab.
+ *
+ * @public
+ */
 export class GitlabUrlReader implements UrlReader {
   static factory: ReaderFactory = ({ config, treeResponseFactory }) => {
     const integrations = ScmIntegrations.fromConfig(config);

packages/backend-common/src/reading/GoogleGcsUrlReader.ts

@@ -48,7 +48,11 @@ const parseURL = (
   };
 };
 
-/** @public */
+/**
+ * Implements a {@link UrlReader} for files on Google GCS.
+ *
+ * @public
+ */
 export class GoogleGcsUrlReader implements UrlReader {
   static factory: ReaderFactory = ({ config, logger }) => {
     if (!config.has('integrations.googleGcs')) {

packages/backend-common/src/reading/UrlReaders.ts

@@ -27,7 +27,11 @@ import { FetchUrlReader } from './FetchUrlReader';
 import { GoogleGcsUrlReader } from './GoogleGcsUrlReader';
 import { AwsS3UrlReader } from './AwsS3UrlReader';
 
-/** @public */
+/**
+ * Creation options for {@link UrlReaders}.
+ *
+ * @public
+ */
 export type UrlReadersOptions = {
   /** Root config object */
   config: Config;
@@ -38,13 +42,13 @@ export type UrlReadersOptions = {
 };
 
 /**
- * UrlReaders provide various utilities related to the UrlReader interface.
+ * Helps construct {@link UrlReader}s.
  *
  * @public
  */
 export class UrlReaders {
   /**
-   * Creates a UrlReader without any known types.
+   * Creates a custom {@link UrlReader} wrapper for your own set of factories.
    */
   static create(options: UrlReadersOptions): UrlReader {
     const { logger, config, factories } = options;
@@ -65,7 +69,8 @@ export class UrlReaders {
   }
 
   /**
-   * Creates a UrlReader that includes all the default factories from this package.
+   * Creates a {@link UrlReader} wrapper that includes all the default factories
+   * from this package.
    *
    * Any additional factories passed will be loaded before the default ones.
    */

packages/backend-common/src/reading/types.ts

@@ -281,7 +281,12 @@ export type FromReadableArrayOptions = Array<{
   path: string;
 }>;
 
-/** @public */
+/**
+ * A factory for response factories that handle the unpacking and inspection of
+ * complex responses such as archive data.
+ *
+ * @public
+ */
 export interface ReadTreeResponseFactory {
   fromTarArchive(
     options: ReadTreeResponseFactoryOptions,

packages/backend-common/src/scm/git.ts

@@ -33,7 +33,11 @@ From : https://isomorphic-git.org/docs/en/onAuth with fix for GitHub
 Azure       'notempty'      token
 */
 
-/** @public */
+/**
+ * A convenience wrapper around the `isomorphic-git` library.
+ *
+ * @public
+ */
 export class Git {
   private constructor(
     private readonly config: {

packages/backend-common/src/service/createStatusCheckRouter.ts

@@ -19,9 +19,26 @@ import Router from 'express-promise-router';
 import express from 'express';
 import { errorHandler, statusCheckHandler, StatusCheck } from '../middleware';
 
-/** @public */
+/**
+ * Creates a default status checking router, that you can add to your express
+ * app.
+ *
+ * @remarks
+ *
+ * This adds a `/healthcheck` route (or any other path, if given as an
+ * argument), which your infra can call to see if the service is ready to serve
+ * requests.
+ *
+ * @public
+ */
 export async function createStatusCheckRouter(options: {
   logger: Logger;
+  /**
+   * The path (including a leading slash) that the health check should be
+   * mounted on.
+   *
+   * @defaultValue '/healthcheck'
+   */
   path?: string;
   /**
    * If not implemented, the default express middleware always returns 200.

packages/backend-common/src/service/types.ts

@@ -20,7 +20,11 @@ import { Router, RequestHandler, ErrorRequestHandler } from 'express';
 import { Server } from 'http';
 import { Logger } from 'winston';
 
-/** @public */
+/**
+ * A helper for building backend service instances.
+ *
+ * @public
+ */
 export type ServiceBuilder = {
   /**
    * Sets the service parameters based on configuration.
@@ -119,5 +123,9 @@ export type ServiceBuilder = {
   start(): Promise<Server>;
 };
 
-/** @public */
+/**
+ * A factory for request loggers.
+ *
+ * @public
+ */
 export type RequestLoggingHandlerFactory = (logger?: Logger) => RequestHandler;

packages/backend-common/src/util/ContainerRunner.ts

@@ -16,7 +16,11 @@
 
 import { Writable } from 'stream';
 
-/** @public */
+/**
+ * Options passed to the {@link ContainerRunner.runContainer} method.
+ *
+ * @public
+ */
 export type RunContainerOptions = {
   imageName: string;
   command?: string | string[];
@@ -28,7 +32,14 @@ export type RunContainerOptions = {
   pullImage?: boolean;
 };
 
-/** @public */
+/**
+ * Handles the running of containers, on behalf of others.
+ *
+ * @public
+ */
 export interface ContainerRunner {
+  /**
+   * Runs a container image to completion.
+   */
   runContainer(opts: RunContainerOptions): Promise<void>;
 }

packages/backend-common/src/util/DockerContainerRunner.ts

@@ -24,7 +24,11 @@ export type UserOptions = {
   User?: string;
 };
 
-/** @public */
+/**
+ * A {@link ContainerRunner} for Docker containers.
+ *
+ * @public
+ */
 export class DockerContainerRunner implements ContainerRunner {
   private readonly dockerClient: Docker;