api report clean ups

Signed-off-by: Emma Indal <emma.indahl@gmail.com>

plugins/techdocs/src/Router.tsx

@@ -19,15 +19,25 @@ import { Entity } from '@backstage/catalog-model';
 import { useEntity } from '@backstage/plugin-catalog-react';
 import { Route, Routes } from 'react-router-dom';
 import { TechDocsIndexPage } from './home/components/TechDocsIndexPage';
-import { TechDocsPage as TechDocsReaderPage } from './reader/components/TechDocsPage';
+import { TechDocsReaderPage } from './reader/components/TechDocsReaderPage';
 import { EntityPageDocs } from './EntityPageDocs';
 import { MissingAnnotationEmptyState } from '@backstage/core-components';
 
 const TECHDOCS_ANNOTATION = 'backstage.io/techdocs-ref';
 
+/**
+ * Helper that takes in entity and returns true/false if TechDocs is available for the entity
+ *
+ * @public
+ */
 export const isTechDocsAvailable = (entity: Entity) =>
   Boolean(entity?.metadata?.annotations?.[TECHDOCS_ANNOTATION]);
 
+/**
+ * Responsible for registering routes for TechDocs, TechDocs Homepage and separate TechDocs page
+ *
+ * @public
+ */
 export const Router = () => {
   return (
     <Routes>
@@ -40,9 +50,12 @@ export const Router = () => {
   );
 };
 
-type Props = {};
-
-export const EmbeddedDocsRouter = (_props: Props) => {
+/**
+ * Responsible for registering route to view docs on Entity page
+ *
+ * @public
+ */
+export const EmbeddedDocsRouter = () => {
   const { entity } = useEntity();
 
   const projectId = entity.metadata.annotations?.[TECHDOCS_ANNOTATION];

plugins/techdocs/src/home/components/DefaultTechDocsHome.tsx

@@ -34,10 +34,9 @@ import {
   UserListFilterKind,
   UserListPicker,
 } from '@backstage/plugin-catalog-react';
-import { EntityListDocsTable } from './EntityListDocsTable';
 import { TechDocsPageWrapper } from './TechDocsPageWrapper';
 import { TechDocsPicker } from './TechDocsPicker';
-import { DocsTableRow } from './types';
+import { DocsTableRow, EntityListDocsTable } from './Tables';
 
 export const DefaultTechDocsHome = ({
   initialFilter = 'all',

plugins/techdocs/src/home/components/LegacyTechDocsHome.tsx

@@ -17,6 +17,9 @@
 import React from 'react';
 import { PanelType, TechDocsCustomHome } from './TechDocsCustomHome';
 
+/**
+ * @deprecated Use {@link TechDocsCustomHome} instead.
+ */
 export const LegacyTechDocsHome = () => {
   const tabsConfig = [
     {

plugins/techdocs/src/home/components/TechDocsCustomHome.tsx

@@ -30,8 +30,8 @@ import {
   parseEntityRef,
   UserEntity,
 } from '@backstage/catalog-model';
-import { DocsTable } from './DocsTable';
-import { DocsCardGrid } from './DocsCardGrid';
+import { DocsTable } from './Tables';
+import { DocsCardGrid } from './Grids';
 import { TechDocsPageWrapper } from './TechDocsPageWrapper';
 
 import {
@@ -51,8 +51,18 @@ const panels = {
   DocsCardGrid: DocsCardGrid,
 };
 
+/**
+ * Available panel types
+ *
+ * @public
+ */
 export type PanelType = 'DocsCardGrid' | 'DocsTable';
 
+/**
+ * Type representing a TechDocsCustomHome panel.
+ *
+ * @public
+ */
 export interface PanelConfig {
   title: string;
   description: string;
@@ -61,11 +71,21 @@ export interface PanelConfig {
   filterPredicate: ((entity: Entity) => boolean) | string;
 }
 
+/**
+ * Type representing a TechDocsCustomHome tab.
+ *
+ * @public
+ */
 export interface TabConfig {
   label: string;
   panels: PanelConfig[];
 }
 
+/**
+ * Type representing a list of TechDocsCustomHome tabs.
+ *
+ * @public
+ */
 export type TabsConfig = TabConfig[];
 
 const CustomPanel = ({

plugins/techdocs/src/home/components/TechDocsPageWrapper.tsx

@@ -19,11 +19,22 @@ import React from 'react';
 import { PageWithHeader } from '@backstage/core-components';
 import { useApi, configApiRef } from '@backstage/core-plugin-api';
 
-type Props = {
+/**
+ * Props for {@link TechDocsPageWrapper}
+ *
+ * @public
+ */
+export type TechDocsPageWrapperProps = {
   children?: React.ReactNode;
 };
 
-export const TechDocsPageWrapper = ({ children }: Props) => {
+/**
+ * Component wrapping a techdocs page with Page and Header components
+ *
+ * @public
+ */
+export const TechDocsPageWrapper = (props: TechDocsPageWrapperProps) => {
+  const { children } = props;
   const configApi = useApi(configApiRef);
   const generatedSubtitle = `Documentation available in ${
     configApi.getOptionalString('organization.name') ?? 'Backstage'

plugins/techdocs/src/home/components/TechDocsPicker.tsx

@@ -34,6 +34,11 @@ type CustomFilters = DefaultEntityFilters & {
   techdocs?: TechDocsFilter;
 };
 
+/**
+ * Component responsible for updating TechDocs filters
+ *
+ * @public
+ */
 export const TechDocsPicker = () => {
   const { updateFilters } = useEntityList<CustomFilters>();
 

plugins/techdocs/src/plugin.ts

@@ -32,6 +32,11 @@ import {
   identityApiRef,
 } from '@backstage/core-plugin-api';
 
+/**
+ * The Backstage plugin that renders technical documentation for your components
+ *
+ * @public
+ */
 export const techdocsPlugin = createPlugin({
   id: 'techdocs',
   apis: [
@@ -73,6 +78,11 @@ export const techdocsPlugin = createPlugin({
   },
 });
 
+/**
+ * Routable extension used to render docs
+ *
+ * @public
+ */
 export const TechdocsPage = techdocsPlugin.provide(
   createRoutableExtension({
     name: 'TechdocsPage',
@@ -81,6 +91,11 @@ export const TechdocsPage = techdocsPlugin.provide(
   }),
 );
 
+/**
+ * Routable extension used to render docs on Entity page
+ *
+ * @public
+ */
 export const EntityTechdocsContent = techdocsPlugin.provide(
   createRoutableExtension({
     name: 'EntityTechdocsContent',
@@ -89,28 +104,11 @@ export const EntityTechdocsContent = techdocsPlugin.provide(
   }),
 );
 
-// takes a list of entities and renders documentation cards
-export const DocsCardGrid = techdocsPlugin.provide(
-  createComponentExtension({
-    name: 'DocsCardGrid',
-    component: {
-      lazy: () =>
-        import('./home/components/DocsCardGrid').then(m => m.DocsCardGrid),
-    },
-  }),
-);
-
-// takes a list of entities and renders table listing documentation
-export const DocsTable = techdocsPlugin.provide(
-  createComponentExtension({
-    name: 'DocsTable',
-    component: {
-      lazy: () => import('./home/components/DocsTable').then(m => m.DocsTable),
-    },
-  }),
-);
-
-// takes a custom tabs config object and renders a documentation landing page
+/**
+ * Component which takes a custom tabs config object and renders a documentation landing page.
+ *
+ * @public
+ */
 export const TechDocsCustomHome = techdocsPlugin.provide(
   createRoutableExtension({
     name: 'TechDocsCustomHome',
@@ -122,6 +120,27 @@ export const TechDocsCustomHome = techdocsPlugin.provide(
   }),
 );
 
+/**
+ * Component which renders a default documentation landing page.
+ *
+ * @public
+ */
+export const DefaultTechDocsHome = techdocsPlugin.provide(
+  createRoutableExtension({
+    name: 'DefaultTechDocsHome',
+    component: () =>
+      import('./home/components/DefaultTechDocsHome').then(
+        m => m.DefaultTechDocsHome,
+      ),
+    mountPoint: rootRouteRef,
+  }),
+);
+
+/**
+ * Responsible for rendering the provided router element
+ *
+ * @public
+ */
 export const TechDocsIndexPage = techdocsPlugin.provide(
   createRoutableExtension({
     name: 'TechDocsIndexPage',
@@ -132,12 +151,3 @@ export const TechDocsIndexPage = techdocsPlugin.provide(
     mountPoint: rootRouteRef,
   }),
 );
-
-export const TechDocsReaderPage = techdocsPlugin.provide(
-  createRoutableExtension({
-    name: 'TechDocsReaderPage',
-    component: () =>
-      import('./reader/components/TechDocsPage').then(m => m.TechDocsPage),
-    mountPoint: rootDocsRouteRef,
-  }),
-);

plugins/techdocs/src/reader/components/LegacyTechDocsPage.tsx

@@ -22,8 +22,11 @@ import { TechDocsNotFound } from './TechDocsNotFound';
 import { useApi } from '@backstage/core-plugin-api';
 import { Page, Content } from '@backstage/core-components';
 import { Reader } from './Reader';
-import { TechDocsPageHeader } from './TechDocsPageHeader';
+import { TechDocsReaderPageHeader } from './TechDocsReaderPageHeader';
 
+/**
+ * @deprecated Use {@link TechDocsPage} instead.
+ */
 export const LegacyTechDocsPage = () => {
   const [documentReady, setDocumentReady] = useState<boolean>(false);
   const { namespace, kind, name } = useParams();
@@ -53,7 +56,7 @@ export const LegacyTechDocsPage = () => {
 
   return (
     <Page themeId="documentation">
-      <TechDocsPageHeader
+      <TechDocsReaderPageHeader
         techDocsMetadata={techdocsMetadataValue}
         entityMetadata={entityMetadataValue}
         entityRef={{

plugins/techdocs/src/reader/components/Reader.tsx

@@ -58,11 +58,16 @@ import {
   copyToClipboard,
 } from '../transformers';
 
-import { TechDocsSearch } from './TechDocsSearch';
+import { TechDocsSearch } from '../../search';
 import { TechDocsStateIndicator } from './TechDocsStateIndicator';
 import { useReaderState } from './useReaderState';
 
-type Props = {
+/**
+ * Props for {@link Reader}
+ *
+ * @public
+ */
+export type ReaderProps = {
   entityRef: EntityName;
   withSearch?: boolean;
   onReady?: () => void;
@@ -823,7 +828,7 @@ const TheReader = ({
   entityRef,
   onReady = () => {},
   withSearch = true,
-}: Props) => {
+}: ReaderProps) => {
   const classes = useStyles();
   const dom = useTechDocsReaderDom(entityRef);
   const shadowDomRef = useRef<HTMLDivElement>(null);
@@ -860,16 +865,20 @@ const TheReader = ({
   );
 };
 
-export const Reader = ({
-  entityRef,
-  onReady = () => {},
-  withSearch = true,
-}: Props) => (
-  <TechDocsReaderProvider entityRef={entityRef}>
-    <TheReader
-      entityRef={entityRef}
-      onReady={onReady}
-      withSearch={withSearch}
-    />
-  </TechDocsReaderProvider>
-);
+/**
+ * Component responsible for rendering TechDocs documentation
+ *
+ * @public
+ */
+export const Reader = (props: ReaderProps) => {
+  const { entityRef, onReady = () => {}, withSearch = true } = props;
+  return (
+    <TechDocsReaderProvider entityRef={entityRef}>
+      <TheReader
+        entityRef={entityRef}
+        onReady={onReady}
+        withSearch={withSearch}
+      />
+    </TechDocsReaderProvider>
+  );
+};

plugins/techdocs/src/types.ts

@@ -16,11 +16,21 @@
 
 import { Entity } from '@backstage/catalog-model';
 
+/**
+ * Metadata for TechDocs page
+ *
+ * @public
+ */
 export type TechDocsMetadata = {
   site_name: string;
   site_description: string;
 };
 
+/**
+ * Metadata for TechDocs Entity
+ *
+ * @public
+ */
 export type TechDocsEntityMetadata = Entity & {
   locationMetadata?: { type: string; target: string };
 };