refactor(techdocs-common): clean up preparer api

Signed-off-by: Camila Belo <camilaibs@gmail.com>

packages/techdocs-common/src/stages/prepare/dir.ts

@@ -24,42 +24,40 @@ import {
 } from '@backstage/integration';
 import { Logger } from 'winston';
 import { parseReferenceAnnotation, transformDirLocation } from '../../helpers';
-import { PreparerBase, PreparerResponse } from './types';
-
-export type DirectoryPreparerOptions = {
-  config: Config;
-  reader: UrlReader;
-};
-
-export type PreparerOptions = { logger?: Logger; etag?: string };
+import {
+  PreparerBase,
+  PreparerOptions,
+  PreparerResponse,
+  DirectoryFactory,
+} from './types';
 
 /**
- * Prepares files before building documentation
- *
+ * Preparer used to retrieve documentation files from a local directory
  * @public
  */
 export class DirectoryPreparer implements PreparerBase {
   private readonly scmIntegrations: ScmIntegrationRegistry;
   private readonly reader: UrlReader;
 
-  /**
-   * @deprecated use static fromConfig method instead.
-   */
+  /**  @deprecated use static fromConfig method instead */
   constructor(config: Config, _logger: Logger | null, reader: UrlReader) {
     this.reader = reader;
     this.scmIntegrations = ScmIntegrations.fromConfig(config);
   }
 
-  static fromConfig(options: DirectoryPreparerOptions): DirectoryPreparer {
-    return new DirectoryPreparer(options.config, null, options.reader);
+  /**
+   * Returns a directory preparer instance
+   * @param config - A backstage config
+   * @param options - A directory preparer options containing the URL reader
+   */
+  static fromConfig(
+    config: Config,
+    options: DirectoryFactory,
+  ): DirectoryPreparer {
+    return new DirectoryPreparer(config, null, options.reader);
   }
 
-  /**
-   *
-   * @param entity - The parts of the format that's common to all versions/kinds of entity
-   * @param options - Optional logger and etag
-   * @returns
-   */
+  /** {@inheritDoc PreparerBase.prepare} */
   async prepare(
     entity: Entity,
     options?: PreparerOptions,

packages/techdocs-common/src/stages/prepare/index.ts

@@ -16,4 +16,14 @@
 export { DirectoryPreparer } from './dir';
 export { UrlPreparer } from './url';
 export { Preparers } from './preparers';
-export type { PreparerBuilder, PreparerBase, RemoteProtocol } from './types';
+export type {
+  PreparerBase,
+  PreparerBuilder,
+  PreparerFactory,
+  PreparerOptions,
+  PreparerResponse,
+  DirectoryFactory,
+  UrlFactory,
+  RemoteProtocol,
+  ETag,
+} from './types';

packages/techdocs-common/src/stages/prepare/preparers.ts

@@ -13,26 +13,34 @@
  * See the License for the specific language governing permissions and
  * limitations under the License.
  */
-import { UrlReader } from '@backstage/backend-common';
 import { Entity } from '@backstage/catalog-model';
 import { Config } from '@backstage/config';
-import { Logger } from 'winston';
 import { parseReferenceAnnotation } from '../../helpers';
 import { DirectoryPreparer } from './dir';
 import { UrlPreparer } from './url';
-import { PreparerBase, PreparerBuilder, RemoteProtocol } from './types';
-
-type factoryOptions = {
-  logger: Logger;
-  reader: UrlReader;
-};
+import {
+  PreparerBase,
+  PreparerBuilder,
+  PreparerFactory,
+  RemoteProtocol,
+} from './types';
 
+/**
+ * Collection of docs preparers
+ * @public
+ */
 export class Preparers implements PreparerBuilder {
   private preparerMap = new Map<RemoteProtocol, PreparerBase>();
 
+  /**
+   * Returns a generators instance containing a generator for Tech Docs
+   * @public
+   * @param config - A Backstage configuration
+   * @param options - Options to configure the URL preparer
+   */
   static async fromConfig(
     config: Config,
-    { logger, reader }: factoryOptions,
+    { logger, reader }: PreparerFactory,
   ): Promise<PreparerBuilder> {
     const preparers = new Preparers();
 
@@ -49,10 +57,20 @@ export class Preparers implements PreparerBuilder {
     return preparers;
   }
 
+  /**
+   * Register a preparer in the preparers collection
+   * @param protocol - url or dir to associate with preparer
+   * @param preparer - The preparer instance to set
+   */
   register(protocol: RemoteProtocol, preparer: PreparerBase) {
     this.preparerMap.set(protocol, preparer);
   }
 
+  /**
+   * Returns the preparer for a given Tech Docs entity
+   * @param entity - A Tech Docs entity instance
+   * @returns
+   */
   get(entity: Entity): PreparerBase {
     const { type } = parseReferenceAnnotation(
       'backstage.io/techdocs-ref',

packages/techdocs-common/src/stages/prepare/types.ts

@@ -15,19 +15,72 @@
  */
 
 import type { Entity } from '@backstage/catalog-model';
+import { UrlReader } from '@backstage/backend-common';
 import { Logger } from 'winston';
 
+/**
+ * Options for building preparers
+ * @public
+ */
+export type PreparerFactory = {
+  logger: Logger;
+  reader: UrlReader;
+};
+
+/**
+ * Options to configure a directory preparer.
+ * @public
+ */
+export type DirectoryFactory = {
+  reader: UrlReader;
+};
+
+/**
+ * Options to configure a url preparer.
+ * @public
+ */
+export type UrlFactory = PreparerFactory;
+
+/**
+ * A unique identifier of the tree blob, usually the commit SHA or etag from the target.
+ * @public
+ */
+export type ETag = string;
+
+/**
+ * Options for configuring the content preparation process.
+ * @public
+ */
+export type PreparerOptions = {
+  /**
+   * An instance of the logger
+   */
+  logger?: Logger;
+  /**
+   * see {@link ETag}
+   */
+  etag?: ETag;
+};
+
+/**
+ * Result of the preparation step.
+ * @public
+ */
 export type PreparerResponse = {
   /**
    * The path to directory where the tree is downloaded.
    */
   preparedDir: string;
   /**
-   * A unique identifier of the tree blob, usually the commit SHA or etag from the target.
+   * see {@link ETag}
    */
-  etag: string;
+  etag: ETag;
 };
 
+/**
+ * Definition of a Tech Docs preparer
+ * @public
+ */
 export type PreparerBase = {
   /**
    * Given an Entity definition from the Software Catalog, go and prepare a directory
@@ -38,15 +91,20 @@ export type PreparerBase = {
    *        updated since the last build.
    * @throws `NotModifiedError` when the prepared directory has not been changed since the last build.
    */
-  prepare(
-    entity: Entity,
-    options?: { logger?: Logger; etag?: string },
-  ): Promise<PreparerResponse>;
+  prepare(entity: Entity, options?: PreparerOptions): Promise<PreparerResponse>;
 };
 
+/**
+ * Definition for a Tech Docs preparer builder
+ * @public
+ */
 export type PreparerBuilder = {
   register(protocol: RemoteProtocol, preparer: PreparerBase): void;
   get(entity: Entity): PreparerBase;
 };
 
+/**
+ * Location where documentation files are stored
+ * @public
+ */
 export type RemoteProtocol = 'url' | 'dir';

packages/techdocs-common/src/stages/prepare/url.ts

@@ -19,17 +19,32 @@ import { UrlReader } from '@backstage/backend-common';
 import { Entity } from '@backstage/catalog-model';
 import { Logger } from 'winston';
 import { getDocFilesFromRepository } from '../../helpers';
-import { PreparerBase, PreparerResponse } from './types';
+import { PreparerBase, PreparerResponse, UrlFactory } from './types';
 
+/**
+ * Preparer used to retrieve documentation files from a remote repository
+ * @public
+ */
 export class UrlPreparer implements PreparerBase {
   private readonly logger: Logger;
   private readonly reader: UrlReader;
 
+  /**  @deprecated use static fromConfig method instead */
   constructor(reader: UrlReader, logger: Logger) {
     this.logger = logger;
     this.reader = reader;
   }
 
+  /**
+   * Returns a directory preparer instance
+   * @param config - A backstage config
+   * @param options - A directory preparer options containing the URL reader
+   */
+  static fromConfig(options: UrlFactory): UrlPreparer {
+    return new UrlPreparer(options.reader, options.logger);
+  }
+
+  /** {@inheritDoc PreparerBase.prepare} */
   async prepare(
     entity: Entity,
     options?: { etag?: string },