From 947dcc465a9528ab96b15a97d2206c3640d2d11f Mon Sep 17 00:00:00 2001
From: Camila Belo <camilaibs@gmail.com>
Date: Wed, 23 Feb 2022 14:30:09 +0100
Subject: [PATCH] refactor(techdocs-common): clean up helpers api

Signed-off-by: Camila Belo <camilaibs@gmail.com>
---
 packages/techdocs-common/src/helpers.ts       | 25 ++++++++++++++++++-
 packages/techdocs-common/src/techdocsTypes.ts | 22 ++++++++++++++++
 2 files changed, 46 insertions(+), 1 deletion(-)

diff --git a/packages/techdocs-common/src/helpers.ts b/packages/techdocs-common/src/helpers.ts
index ccf1256381..9075660c0e 100644
--- a/packages/techdocs-common/src/helpers.ts
+++ b/packages/techdocs-common/src/helpers.ts
@@ -26,11 +26,21 @@ import path from 'path';
 import { Logger } from 'winston';
 import { PreparerResponse, RemoteProtocol } from './stages/prepare/types';
 
+/**
+ * Parsed location annotation
+ * @public
+ */
 export type ParsedLocationAnnotation = {
   type: RemoteProtocol;
   target: string;
 };
 
+/**
+ * Returns a parset locations annotation
+ * @public
+ * @param annotationName - The name of the annotation in the entity metadata
+ * @param entity - A Tech Docs entity instance
+ */
 export const parseReferenceAnnotation = (
   annotationName: string,
   entity: Entity,
@@ -56,7 +66,7 @@ export const parseReferenceAnnotation = (
  * location, it returns a `url` location with a resolved target that points to the
  * targeted subfolder. If the entity was registered by a `file` location, it returns
  * an absolute `dir` location.
- *
+ * @public
  * @param entity - the entity with annotations
  * @param dirAnnotation - the parsed techdocs-ref annotation of type 'dir'
  * @param scmIntegrations - access to the scmIntegration to do url transformations
@@ -101,6 +111,12 @@ export const transformDirLocation = (
   }
 };
 
+/**
+ * Returns a entity reference based on the Tech Docs annotation type
+ * @public
+ * @param entity - A Tech Docs instance
+ * @param scmIntegration - An implementation for  SCM integration API
+ */
 export const getLocationForEntity = (
   entity: Entity,
   scmIntegration: ScmIntegrationRegistry,
@@ -120,6 +136,13 @@ export const getLocationForEntity = (
   }
 };
 
+/**
+ * Returns a preparer response {@link PreparerResponse}
+ * @public
+ * @param reader - Read a tree of files from a repository
+ * @param entity - A Tech Docs entity instance
+ * @param opts - Options for configuring the reader, e.g. logger, etag, etc.
+ */
 export const getDocFilesFromRepository = async (
   reader: UrlReader,
   entity: Entity,
diff --git a/packages/techdocs-common/src/techdocsTypes.ts b/packages/techdocs-common/src/techdocsTypes.ts
index 4aa3972b31..69f7b36e9f 100644
--- a/packages/techdocs-common/src/techdocsTypes.ts
+++ b/packages/techdocs-common/src/techdocsTypes.ts
@@ -16,11 +16,33 @@
 
 import { IndexableDocument } from '@backstage/search-common';
 
+/**
+ * Tech Docs indexable document interface
+ * @public
+ */
 export interface TechDocsDocument extends IndexableDocument {
+  /**
+   * Entity kind
+   */
   kind: string;
+  /**
+   * Entity metadata namespace
+   */
   namespace: string;
+  /**
+   * Entity metadata name
+   */
   name: string;
+  /**
+   * Entity lifecycle
+   */
   lifecycle: string;
+  /**
+   * Entity owner
+   */
   owner: string;
+  /**
+   * Entity path
+   */
   path: string;
 }