Do not unpack arguments directly on exported items

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

packages/techdocs-common/api-report.md

@@ -49,22 +49,6 @@ export type GeneratorBuilder = {
   get(entity: Entity): GeneratorBase;
 };
 
-// Warning: (tsdoc-param-tag-missing-hyphen) The @param block should be followed by a parameter name and then a hyphen
-// Warning: (tsdoc-param-tag-with-invalid-type) The @param block should not include a JSDoc-style '{type}'
-// Warning: (tsdoc-param-tag-missing-hyphen) The @param block should be followed by a parameter name and then a hyphen
-// Warning: (tsdoc-param-tag-with-invalid-type) The @param block should not include a JSDoc-style '{type}'
-// Warning: (tsdoc-param-tag-missing-hyphen) The @param block should be followed by a parameter name and then a hyphen
-// Warning: (tsdoc-param-tag-with-invalid-type) The @param block should not include a JSDoc-style '{type}'
-// Warning: (tsdoc-param-tag-missing-hyphen) The @param block should be followed by a parameter name and then a hyphen
-// Warning: (tsdoc-param-tag-with-invalid-type) The @param block should not include a JSDoc-style '{type}'
-// Warning: (tsdoc-param-tag-missing-hyphen) The @param block should be followed by a parameter name and then a hyphen
-// Warning: (tsdoc-param-tag-with-invalid-optional-name) The @param should not include a JSDoc-style optional name; it must not be enclosed in '[ ]' brackets.
-// Warning: (tsdoc-param-tag-with-invalid-type) The @param block should not include a JSDoc-style '{type}'
-// Warning: (tsdoc-param-tag-missing-hyphen) The @param block should be followed by a parameter name and then a hyphen
-// Warning: (tsdoc-param-tag-with-invalid-optional-name) The @param should not include a JSDoc-style optional name; it must not be enclosed in '[ ]' brackets.
-// Warning: (tsdoc-param-tag-with-invalid-type) The @param block should not include a JSDoc-style '{type}'
-// Warning: (ae-missing-release-tag) "GeneratorRunOptions" is exported by the package, but it is missing a release tag (@alpha, @beta, @public, or @internal)
-//
 // @public
 export type GeneratorRunOptions = {
   inputDir: string;
@@ -82,10 +66,7 @@ export class Generators implements GeneratorBuilder {
   // (undocumented)
   static fromConfig(
     config: Config,
-    {
-      logger,
-      containerRunner,
-    }: {
+    options: {
       logger: Logger_2;
       containerRunner: ContainerRunner;
     },
@@ -185,13 +166,10 @@ export class Publisher {
   ): Promise<PublisherBase>;
 }
 
-// Warning: (ae-missing-release-tag) "PublisherBase" is exported by the package, but it is missing a release tag (@alpha, @beta, @public, or @internal)
-//
 // @public
 export interface PublisherBase {
   docsRouter(): express.Handler;
   fetchTechDocsMetadata(entityName: EntityName): Promise<TechDocsMetadata>;
-  // Warning: (ae-forgotten-export) The symbol "ReadinessResponse" needs to be exported by the entry point index.d.ts
   getReadiness(): Promise<ReadinessResponse>;
   hasDocsBeenGenerated(entityName: Entity): Promise<boolean>;
   // Warning: (tsdoc-escape-right-brace) The "}" character should be escaped using a backslash to avoid confusion with a TSDoc inline tag
@@ -202,7 +180,6 @@ export interface PublisherBase {
   // Warning: (tsdoc-malformed-inline-tag) Expecting a TSDoc tag starting with "{@"
   // Warning: (ae-forgotten-export) The symbol "MigrateRequest" needs to be exported by the entry point index.d.ts
   migrateDocsCase?(migrateRequest: MigrateRequest): Promise<void>;
-  // Warning: (tsdoc-param-tag-missing-hyphen) The @param block should be followed by a parameter name and then a hyphen
   // Warning: (ae-forgotten-export) The symbol "PublishRequest" needs to be exported by the entry point index.d.ts
   // Warning: (ae-forgotten-export) The symbol "PublishResponse" needs to be exported by the entry point index.d.ts
   publish(request: PublishRequest): Promise<PublishResponse>;
@@ -218,6 +195,11 @@ export type PublisherType =
   | 'azureBlobStorage'
   | 'openStackSwift';
 
+// @public
+export type ReadinessResponse = {
+  isAvailable: boolean;
+};
+
 // Warning: (ae-missing-release-tag) "RemoteProtocol" is exported by the package, but it is missing a release tag (@alpha, @beta, @public, or @internal)
 //
 // @public (undocumented)
@@ -245,12 +227,7 @@ export interface TechDocsDocument extends IndexableDocument {
 //
 // @public (undocumented)
 export class TechdocsGenerator implements GeneratorBase {
-  constructor({
-    logger,
-    containerRunner,
-    config,
-    scmIntegrations,
-  }: {
+  constructor(options: {
     logger: Logger_2;
     containerRunner: ContainerRunner;
     config: Config;
@@ -260,26 +237,15 @@ export class TechdocsGenerator implements GeneratorBase {
   // (undocumented)
   static fromConfig(
     config: Config,
-    {
-      containerRunner,
-      logger,
-    }: {
+    options: {
       containerRunner: ContainerRunner;
       logger: Logger_2;
     },
   ): TechdocsGenerator;
   // (undocumented)
-  run({
-    inputDir,
-    outputDir,
-    parsedLocationAnnotation,
-    etag,
-    logger: childLogger,
-    logStream,
-  }: GeneratorRunOptions): Promise<void>;
+  run(options: GeneratorRunOptions): Promise<void>;
 }
 
-// Warning: (tsdoc-param-tag-missing-hyphen) The @param block should be followed by a parameter name and then a hyphen
 // Warning: (ae-missing-release-tag) "TechDocsMetadata" is exported by the package, but it is missing a release tag (@alpha, @beta, @public, or @internal)
 //
 // @public
@@ -319,7 +285,7 @@ export class UrlPreparer implements PreparerBase {
 
 // Warnings were encountered during analysis:
 //
-// src/stages/generate/types.d.ts:44:5 - (ae-forgotten-export) The symbol "SupportedGeneratorKey" needs to be exported by the entry point index.d.ts
+// src/stages/generate/types.d.ts:45:5 - (ae-forgotten-export) The symbol "SupportedGeneratorKey" needs to be exported by the entry point index.d.ts
 // src/stages/prepare/types.d.ts:18:8 - (tsdoc-param-tag-missing-hyphen) The @param block should be followed by a parameter name and then a hyphen
 // src/stages/prepare/types.d.ts:19:8 - (tsdoc-param-tag-with-invalid-name) The @param block should be followed by a valid parameter name: The identifier cannot non-word characters
 // src/stages/prepare/types.d.ts:21:33 - (tsdoc-escape-right-brace) The "}" character should be escaped using a backslash to avoid confusion with a TSDoc inline tag

packages/techdocs-common/src/stages/generate/generators.ts

@@ -31,17 +31,11 @@ export class Generators implements GeneratorBuilder {
 
   static async fromConfig(
     config: Config,
-    {
-      logger,
-      containerRunner,
-    }: { logger: Logger; containerRunner: ContainerRunner },
+    options: { logger: Logger; containerRunner: ContainerRunner },
   ): Promise<GeneratorBuilder> {
     const generators = new Generators();
 
-    const techdocsGenerator = TechdocsGenerator.fromConfig(config, {
-      logger,
-      containerRunner,
-    });
+    const techdocsGenerator = TechdocsGenerator.fromConfig(config, options);
     generators.register('techdocs', techdocsGenerator);
 
     return generators;

packages/techdocs-common/src/stages/generate/techdocs.ts

@@ -52,11 +52,9 @@ export class TechdocsGenerator implements GeneratorBase {
 
   static fromConfig(
     config: Config,
-    {
-      containerRunner,
-      logger,
-    }: { containerRunner: ContainerRunner; logger: Logger },
+    options: { containerRunner: ContainerRunner; logger: Logger },
   ) {
+    const { containerRunner, logger } = options;
     const scmIntegrations = ScmIntegrations.fromConfig(config);
     return new TechdocsGenerator({
       logger,
@@ -66,31 +64,28 @@ export class TechdocsGenerator implements GeneratorBase {
     });
   }
 
-  constructor({
-    logger,
-    containerRunner,
-    config,
-    scmIntegrations,
-  }: {
+  constructor(options: {
     logger: Logger;
     containerRunner: ContainerRunner;
     config: Config;
     scmIntegrations: ScmIntegrationRegistry;
   }) {
-    this.logger = logger;
-    this.options = readGeneratorConfig(config, logger);
-    this.containerRunner = containerRunner;
-    this.scmIntegrations = scmIntegrations;
+    this.logger = options.logger;
+    this.options = readGeneratorConfig(options.config, options.logger);
+    this.containerRunner = options.containerRunner;
+    this.scmIntegrations = options.scmIntegrations;
   }
 
-  public async run({
-    inputDir,
-    outputDir,
-    parsedLocationAnnotation,
-    etag,
-    logger: childLogger,
-    logStream,
-  }: GeneratorRunOptions): Promise<void> {
+  public async run(options: GeneratorRunOptions): Promise<void> {
+    const {
+      inputDir,
+      outputDir,
+      parsedLocationAnnotation,
+      etag,
+      logger: childLogger,
+      logStream,
+    } = options;
+
     // Do some updates to mkdocs.yml before generating docs e.g. adding repo_url
     const { path: mkdocsYmlPath, content } = await getMkdocsYml(inputDir);
 

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

@@ -34,12 +34,13 @@ export type GeneratorConfig = {
 /**
  * The values that the generator will receive.
  *
- * @param {string} inputDir The directory of the uncompiled documentation, with the values from the frontend
- * @param {string} outputDir Directory to store generated docs in. Usually - a newly created temporary directory.
- * @param {ParsedLocationAnnotation} parsedLocationAnnotation backstage.io/techdocs-ref annotation of an entity
- * @param {string} etag A unique identifier for the prepared tree e.g. commit SHA. If provided it will be stored in techdocs_metadata.json.
- * @param {Logger} [logger] A logger that forwards the messages to the caller to be displayed outside of the backend.
- * @param {Writable} [logStream] A log stream that can send raw log messages to the caller to be displayed outside of the backend..
+ * @public
+ * @param inputDir - The directory of the uncompiled documentation, with the values from the frontend
+ * @param outputDir - Directory to store generated docs in. Usually - a newly created temporary directory.
+ * @param parsedLocationAnnotation - backstage.io/techdocs-ref annotation of an entity
+ * @param etag - A unique identifier for the prepared tree e.g. commit SHA. If provided it will be stored in techdocs_metadata.json.
+ * @param logger - A logger that forwards the messages to the caller to be displayed outside of the backend.
+ * @param logStream - A log stream that can send raw log messages to the caller to be displayed outside of the backend.
  */
 export type GeneratorRunOptions = {
   inputDir: string;

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

@@ -14,4 +14,9 @@
  * limitations under the License.
  */
 export { Publisher } from './publish';
-export type { PublisherBase, PublisherType, TechDocsMetadata } from './types';
+export type {
+  PublisherBase,
+  PublisherType,
+  TechDocsMetadata,
+  ReadinessResponse,
+} from './types';

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

@@ -51,6 +51,8 @@ export type PublishResponse = {
 
 /**
  * Result for the validation check.
+ *
+ * @public
  */
 export type ReadinessResponse = {
   /** If true, the publisher is able to interact with the backing storage. */
@@ -59,7 +61,7 @@ export type ReadinessResponse = {
 
 /**
  * Type to hold metadata found in techdocs_metadata.json and associated with each site
- * @param etag ETag of the resource used to generate the site. Usually the latest commit sha of the source repository.
+ * @param etag - ETag of the resource used to generate the site. Usually the latest commit sha of the source repository.
  */
 export type TechDocsMetadata = {
   site_name: string;
@@ -86,6 +88,8 @@ export type MigrateRequest = {
  * Base class for a TechDocs publisher (e.g. Local, Google GCS Bucket, AWS S3, etc.)
  * The publisher handles publishing of the generated static files after the prepare and generate steps of TechDocs.
  * It also provides APIs to communicate with the storage service.
+ *
+ * @public
  */
 export interface PublisherBase {
   /**
@@ -99,8 +103,8 @@ export interface PublisherBase {
   /**
    * Store the generated static files onto a storage service (either local filesystem or external service).
    *
-   * @param request Object containing the entity from the service
-   * catalog, and the directory that contains the generated static files from TechDocs.
+   * @param request - Object containing the entity from the service
+   *                  catalog, and the directory that contains the generated static files from TechDocs.
    */
   publish(request: PublishRequest): Promise<PublishResponse>;