update comments and api reports

Signed-off-by: Chris Suich <csuich2@gmail.com>

plugins/techdocs-common/report.api.md

@@ -8,4 +8,8 @@ export const TECHDOCS_ANNOTATION = 'backstage.io/techdocs-ref';
 
 // @public (undocumented)
 export const TECHDOCS_EXTERNAL_ANNOTATION = 'backstage.io/techdocs-entity';
+
+// @public (undocumented)
+export const TECHDOCS_EXTERNAL_PATH_ANNOTATION =
+  'backstage.io/techdocs-entity-path';
 ```

plugins/techdocs-react/report.api.md

@@ -15,8 +15,15 @@ import { JSX as JSX_2 } from 'react/jsx-runtime';
 import { MemoExoticComponent } from 'react';
 import { PropsWithChildren } from 'react';
 import { ReactNode } from 'react';
+import { RouteFunc } from '@backstage/core-plugin-api';
 import { SetStateAction } from 'react';
 
+// @public
+export const buildTechDocsURL: (
+  entity: Entity,
+  routeFunc: TechDocsRouteFunc | undefined,
+) => string | undefined;
+
 // @public
 export function createTechDocsAddonExtension(
   options: TechDocsAddonOptions,
@@ -27,6 +34,9 @@ export function createTechDocsAddonExtension<TComponentProps>(
   options: TechDocsAddonOptions<TComponentProps>,
 ): Extension<(props: TComponentProps) => JSX.Element | null>;
 
+// @public
+export function getEntityRootTechDocsPath(entity: Entity): string;
+
 // @public
 export const SHADOW_DOM_STYLE_LOAD_EVENT = 'TECH_DOCS_SHADOW_DOM_STYLE_LOAD';
 
@@ -122,6 +132,13 @@ export type TechDocsReaderPageValue = {
   onReady?: () => void;
 };
 
+// @public
+export type TechDocsRouteFunc = RouteFunc<{
+  namespace: string;
+  kind: string;
+  name: string;
+}>;
+
 // @public
 export const TechDocsShadowDom: (
   props: TechDocsShadowDomProps,

plugins/techdocs-react/src/helpers.ts

@@ -27,6 +27,12 @@ import {
 } from '@backstage/plugin-techdocs-common';
 import { RouteFunc } from '@backstage/core-plugin-api';
 
+/**
+ * The RouteFunc used by buildTechDocsURL() to build the TechDocs link for
+ * an entity.
+ *
+ * @public
+ */
 export type TechDocsRouteFunc = RouteFunc<{
   namespace: string;
   kind: string;
@@ -52,6 +58,11 @@ export function toLowercaseEntityRefMaybe(
   return entityRef;
 }
 
+/**
+ * Get the entity path annotation from the given entity and ensure it starts with a slash.
+ *
+ * @public
+ */
 export function getEntityRootTechDocsPath(entity: Entity): string {
   let path = entity.metadata.annotations?.[TECHDOCS_EXTERNAL_PATH_ANNOTATION];
   if (!path) {
@@ -63,6 +74,12 @@ export function getEntityRootTechDocsPath(entity: Entity): string {
   return path;
 }
 
+/**
+ * Build the TechDocs URL for the given entity. This helper should be used anywhere there
+ * is a link to an entities TechDocs.
+ *
+ * @public
+ */
 export const buildTechDocsURL = (
   entity: Entity,
   routeFunc: TechDocsRouteFunc | undefined,