From 7a9b906ec741681187de47d8dbc002353cb5c8b7 Mon Sep 17 00:00:00 2001
From: Camila Belo <camilaibs@gmail.com>
Date: Wed, 23 Feb 2022 14:29:42 +0100
Subject: [PATCH] refactor(techdocs-common): clean up publish api

Signed-off-by: Camila Belo <camilaibs@gmail.com>
---
 .../src/stages/publish/index.ts               |  6 ++++-
 .../src/stages/publish/publish.ts             | 17 +++++++-------
 .../src/stages/publish/types.ts               | 23 ++++++++++++++++++-
 3 files changed, 35 insertions(+), 11 deletions(-)

diff --git a/packages/techdocs-common/src/stages/publish/index.ts b/packages/techdocs-common/src/stages/publish/index.ts
index 083cf2b8ff..c6f86f6bc1 100644
--- a/packages/techdocs-common/src/stages/publish/index.ts
+++ b/packages/techdocs-common/src/stages/publish/index.ts
@@ -17,6 +17,10 @@ export { Publisher } from './publish';
 export type {
   PublisherBase,
   PublisherType,
-  TechDocsMetadata,
+  PublisherFactory,
+  PublishRequest,
+  PublishResponse,
+  MigrateRequest,
   ReadinessResponse,
+  TechDocsMetadata,
 } from './types';
diff --git a/packages/techdocs-common/src/stages/publish/publish.ts b/packages/techdocs-common/src/stages/publish/publish.ts
index eb9e3104bf..b9ea4c7cb4 100644
--- a/packages/techdocs-common/src/stages/publish/publish.ts
+++ b/packages/techdocs-common/src/stages/publish/publish.ts
@@ -14,29 +14,28 @@
  * limitations under the License.
  */
 
-import { PluginEndpointDiscovery } from '@backstage/backend-common';
 import { Config } from '@backstage/config';
-import { Logger } from 'winston';
 import { AwsS3Publish } from './awsS3';
 import { AzureBlobStoragePublish } from './azureBlobStorage';
 import { GoogleGCSPublish } from './googleStorage';
 import { LocalPublish } from './local';
 import { OpenStackSwiftPublish } from './openStackSwift';
-import { PublisherBase, PublisherType } from './types';
-
-type factoryOptions = {
-  logger: Logger;
-  discovery: PluginEndpointDiscovery;
-};
+import { PublisherFactory, PublisherBase, PublisherType } from './types';
 
 /**
  * Factory class to create a TechDocs publisher based on defined publisher type in app config.
  * Uses `techdocs.publisher.type`.
+ * @public
  */
 export class Publisher {
+  /**
+   * Returns a instance of Tech Docs publisher
+   * @param config - A Backstage configuration
+   * @param options - Options for configuring the publisher factory
+   */
   static async fromConfig(
     config: Config,
-    { logger, discovery }: factoryOptions,
+    { logger, discovery }: PublisherFactory,
   ): Promise<PublisherBase> {
     const publisherType = (config.getOptionalString(
       'techdocs.publisher.type',
diff --git a/packages/techdocs-common/src/stages/publish/types.ts b/packages/techdocs-common/src/stages/publish/types.ts
index 37075a35a4..0c3c047b40 100644
--- a/packages/techdocs-common/src/stages/publish/types.ts
+++ b/packages/techdocs-common/src/stages/publish/types.ts
@@ -14,10 +14,22 @@
  * limitations under the License.
  */
 import { Entity, EntityName } from '@backstage/catalog-model';
+import { PluginEndpointDiscovery } from '@backstage/backend-common';
+import { Logger } from 'winston';
 import express from 'express';
 
+/**
+ * Options for building publishers
+ * @public
+ */
+export type PublisherFactory = {
+  logger: Logger;
+  discovery: PluginEndpointDiscovery;
+};
+
 /**
  * Key for all the different types of TechDocs publishers that are supported.
+ * @public
  */
 export type PublisherType =
   | 'local'
@@ -26,6 +38,10 @@ export type PublisherType =
   | 'azureBlobStorage'
   | 'openStackSwift';
 
+/**
+ * Request publish definition
+ * @public
+ */
 export type PublishRequest = {
   entity: Entity;
   /* The Path to the directory where the generated files are stored. */
@@ -35,6 +51,7 @@ export type PublishRequest = {
 /**
  * Response containing metadata about where files were published and what may
  * have been published or updated.
+ * @public
  */
 export type PublishResponse = {
   /**
@@ -51,7 +68,6 @@ export type PublishResponse = {
 
 /**
  * Result for the validation check.
- *
  * @public
  */
 export type ReadinessResponse = {
@@ -62,6 +78,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.
+ * @public
  */
 export type TechDocsMetadata = {
   site_name: string;
@@ -71,6 +88,10 @@ export type TechDocsMetadata = {
   files?: string[];
 };
 
+/**
+ * Tech Docs entity triplet migration request
+ * @public
+ */
 export type MigrateRequest = {
   /**
    * Whether or not to remove the source file. Defaults to false (acting like a