Improve API Reference in Tech Radar Plugin

Signed-off-by: Tomasz Szuba <tszuba@box.com>

plugins/tech-radar/api-report.md

@@ -9,138 +9,114 @@ import { ApiRef } from '@backstage/core-plugin-api';
 import { BackstagePlugin } from '@backstage/core-plugin-api';
 import { RouteRef } from '@backstage/core-plugin-api';
 
+// Warning: (ae-missing-release-tag) "MovedState" is exported by the package, but it is missing a release tag (@alpha, @beta, @public, or @internal)
+//
+// @public
+export enum MovedState {
+  Down = -1,
+  NoChange = 0,
+  Up = 1,
+}
+
 // Warning: (ae-missing-release-tag) "RadarEntry" is exported by the package, but it is missing a release tag (@alpha, @beta, @public, or @internal)
 //
-// @public (undocumented)
+// @public
 export interface RadarEntry {
-  // (undocumented)
   description?: string;
-  // (undocumented)
   id: string;
-  // (undocumented)
   key: string;
-  // (undocumented)
   quadrant: string;
-  // (undocumented)
   timeline: Array<RadarEntrySnapshot>;
-  // (undocumented)
   title: string;
-  // (undocumented)
   url: string;
 }
 
 // Warning: (ae-missing-release-tag) "RadarEntrySnapshot" is exported by the package, but it is missing a release tag (@alpha, @beta, @public, or @internal)
 //
-// @public (undocumented)
+// @public
 export interface RadarEntrySnapshot {
-  // (undocumented)
   date: Date;
-  // (undocumented)
   description?: string;
-  // Warning: (ae-forgotten-export) The symbol "MovedState" needs to be exported by the entry point index.d.ts
-  //
-  // (undocumented)
   moved?: MovedState;
-  // (undocumented)
   ringId: string;
 }
 
 // Warning: (ae-missing-release-tag) "RadarQuadrant" is exported by the package, but it is missing a release tag (@alpha, @beta, @public, or @internal)
 //
-// @public (undocumented)
+// @public
 export interface RadarQuadrant {
-  // (undocumented)
   id: string;
-  // (undocumented)
   name: string;
 }
 
 // Warning: (ae-missing-release-tag) "RadarRing" is exported by the package, but it is missing a release tag (@alpha, @beta, @public, or @internal)
 //
-// @public (undocumented)
+// @public
 export interface RadarRing {
-  // (undocumented)
   color: string;
-  // (undocumented)
   id: string;
-  // (undocumented)
   name: string;
 }
 
 // Warning: (ae-missing-release-tag) "RadarPage" is exported by the package, but it is missing a release tag (@alpha, @beta, @public, or @internal)
 //
-// @public (undocumented)
-export const Router: {
-  ({ title, subtitle, pageTitle, ...props }: TechRadarPageProps): JSX.Element;
-  defaultProps: {
-    title: string;
-    subtitle: string;
-    pageTitle: string;
-  };
-};
+// @public
+export function Router(props: TechRadarPageProps): JSX.Element;
 
 // Warning: (ae-missing-release-tag) "TechRadarApi" is exported by the package, but it is missing a release tag (@alpha, @beta, @public, or @internal)
 //
-// @public (undocumented)
+// @public
 export interface TechRadarApi {
   load: (id: string | undefined) => Promise<TechRadarLoaderResponse>;
 }
 
 // Warning: (ae-missing-release-tag) "techRadarApiRef" is exported by the package, but it is missing a release tag (@alpha, @beta, @public, or @internal)
 //
-// @public (undocumented)
+// @public
 export const techRadarApiRef: ApiRef<TechRadarApi>;
 
 // Warning: (ae-missing-release-tag) "RadarComponent" is exported by the package, but it is missing a release tag (@alpha, @beta, @public, or @internal)
 //
-// @public (undocumented)
-export const TechRadarComponent: (
-  props: TechRadarComponentProps,
-) => JSX.Element;
+// @public
+export function TechRadarComponent(props: TechRadarComponentProps): JSX.Element;
 
 // Warning: (ae-missing-release-tag) "TechRadarComponentProps" is exported by the package, but it is missing a release tag (@alpha, @beta, @public, or @internal)
 //
-// @public (undocumented)
+// @public
 export interface TechRadarComponentProps {
-  // (undocumented)
   height: number;
-  // (undocumented)
   id?: string;
-  // (undocumented)
   searchText?: string;
-  // (undocumented)
   svgProps?: object;
-  // (undocumented)
   width: number;
 }
 
 // Warning: (ae-missing-release-tag) "TechRadarLoaderResponse" is exported by the package, but it is missing a release tag (@alpha, @beta, @public, or @internal)
 //
-// @public (undocumented)
+// @public
 export interface TechRadarLoaderResponse {
-  // (undocumented)
   entries: RadarEntry[];
-  // (undocumented)
   quadrants: RadarQuadrant[];
-  // (undocumented)
   rings: RadarRing[];
 }
 
 // Warning: (ae-missing-release-tag) "TechRadarPage" is exported by the package, but it is missing a release tag (@alpha, @beta, @public, or @internal)
 //
-// @public (undocumented)
-export const TechRadarPage: {
-  ({ title, subtitle, pageTitle, ...props }: TechRadarPageProps): JSX.Element;
-  defaultProps: {
-    title: string;
-    subtitle: string;
-    pageTitle: string;
-  };
+// @public
+export const TechRadarPage: Router;
+
+// Warning: (ae-missing-release-tag) "TechRadarPageProps" is exported by the package, but it is missing a release tag (@alpha, @beta, @public, or @internal)
+//
+// @public
+export type TechRadarPageProps = TechRadarComponentProps & {
+  title?: string;
+  subtitle?: string;
+  pageTitle?: string;
 };
 
 // Warning: (ae-missing-release-tag) "techRadarPlugin" is exported by the package, but it is missing a release tag (@alpha, @beta, @public, or @internal)
 //
-// @public (undocumented)
+// @public
 const techRadarPlugin: BackstagePlugin<
   {
     root: RouteRef<undefined>;
@@ -149,8 +125,4 @@ const techRadarPlugin: BackstagePlugin<
 >;
 export { techRadarPlugin as plugin };
 export { techRadarPlugin };
-
-// Warnings were encountered during analysis:
-//
-// src/components/RadarPage.d.ts:9:5 - (ae-forgotten-export) The symbol "TechRadarPageProps" needs to be exported by the entry point index.d.ts
 ```

plugins/tech-radar/src/api.ts

@@ -13,15 +13,26 @@
  * See the License for the specific language governing permissions and
  * limitations under the License.
  */
+import { ApiRef, createApiRef } from '@backstage/core-plugin-api';
 
-import { MovedState } from './utils/types';
-import { createApiRef } from '@backstage/core-plugin-api';
-
-export const techRadarApiRef = createApiRef<TechRadarApi>({
-  id: 'plugin.techradar.service',
-  description: 'Used to populate data in the TechRadar plugin',
-});
+/**
+ * {@link @backstage/core-plugin-api#ApiRef} for the {@link TechRadarApi}
+ */
+export const techRadarApiRef: ApiRef<TechRadarApi> = createApiRef<TechRadarApi>(
+  {
+    id: 'plugin.techradar.service',
+    description: 'Used to populate data in the TechRadar plugin',
+  },
+);
 
+/**
+ * Tech Radar API responsible for loading data for the plugin
+ *
+ * @remarks
+ *
+ * This should be implemented by user, as {@link https://github.com/backstage/backstage/blob/master/plugins/tech-radar/src/sample.ts | default}
+ * serves only some static data for example purposes
+ */
 export interface TechRadarApi {
   /**
    * Loads the TechRadar response data to pass through to the TechRadar component.
@@ -34,41 +45,139 @@ export interface TechRadarApi {
  * Types related to the Radar's visualization.
  */
 
+/**
+ * Tech Radar Ring which indicates stage of {@link RadarEntry}
+ */
 export interface RadarRing {
+  /**
+   * ID of the Ring
+   */
   id: string;
+  /**
+   * Display name of the Ring
+   */
   name: string;
+  /**
+   * Color used for entries in particular Ring
+   *
+   * @remarks
+   *
+   * Supports any value parseable by {@link https://www.npmjs.com/package/color-string | color-string}
+   */
   color: string;
 }
 
+/**
+ * Tech Radar Quadrant which represent area/topic of {@link RadarEntry}
+ */
 export interface RadarQuadrant {
+  /**
+   * ID of the Quadrant
+   */
   id: string;
+  /**
+   * Display name of the Quadrant
+   */
   name: string;
 }
 
+/**
+ * Single Entry in Tech Radar
+ */
 export interface RadarEntry {
-  key: string; // react key
+  /**
+   * React key to use for this Entry
+   */
+  key: string;
+  /**
+   * ID of this Radar Entry
+   */
   id: string;
+  /**
+   * ID of {@link RadarQuadrant} this Entry belongs to
+   */
   quadrant: string;
+  /**
+   * Display name of the Entry
+   */
   title: string;
+  /**
+   * User-clickable URL when rendered in Radar
+   *
+   * @remarks
+   *
+   * You can use `#` if you don't want to provide any other url
+   */
   url: string;
+  /**
+   * History of the Entry moving through {@link RadarRing}
+   */
   timeline: Array<RadarEntrySnapshot>;
+  /**
+   * Description of the Entry
+   */
   description?: string;
 }
 
+/**
+ * State of {@link RadarEntry} at given point in time
+ */
 export interface RadarEntrySnapshot {
+  /**
+   * Point in time when change happened
+   */
   date: Date;
+  /**
+   * ID of {@link RadarRing}
+   */
   ringId: string;
+  /**
+   * Description of change
+   */
   description?: string;
+  /**
+   * Indicates trend compared to previous snapshot
+   */
   moved?: MovedState;
 }
 
+/**
+ * Indicates how {@link RadarEntry} moved though {@link RadarRing} on {@link RadarEntry.timeline}
+ */
+export enum MovedState {
+  /**
+   * Moved down
+   */
+  Down = -1,
+  /**
+   * Didn't move
+   */
+  NoChange = 0,
+  /**
+   * Move up
+   */
+  Up = 1,
+}
+
 /*
  * Types related to data collection for the Radar.
  */
 
+/**
+ * Response from {@link TechRadarApi}
+ */
 export interface TechRadarLoaderResponse {
+  /**
+   * Quadrant of Tech Radar. Should be 4
+   */
   quadrants: RadarQuadrant[];
+  /**
+   * Rings of Tech Radar
+   */
   rings: RadarRing[];
+  /**
+   * Entries visualised in Tech Radar
+   */
   entries: RadarEntry[];
 }
 
@@ -76,10 +185,50 @@ export interface TechRadarLoaderResponse {
  * Set up the Radar as a Backstage component.
  */
 
+/**
+ * Properties of {@link TechRadarComponent}
+ */
 export interface TechRadarComponentProps {
+  /**
+   * ID of this Tech Radar
+   *
+   * @remarks
+   *
+   * Used when there are multiple Tech Radars and passed to {@link TechRadarApi.load}
+   */
   id?: string;
+  /**
+   * Width of Tech Radar
+   */
   width: number;
+  /**
+   * Height of Tech Radar
+   */
   height: number;
+  /**
+   * Custom React props to the `<svg>` element created for Tech Radar
+   */
   svgProps?: object;
+  /**
+   * Text to filter {@link RadarEntry} inside Tech Radar
+   */
   searchText?: string;
 }
+
+/**
+ * Properties for {@link TechRadarPage}
+ */
+export type TechRadarPageProps = TechRadarComponentProps & {
+  /**
+   * Title
+   */
+  title?: string;
+  /**
+   * Subtitle
+   */
+  subtitle?: string;
+  /**
+   * Page Title
+   */
+  pageTitle?: string;
+};

plugins/tech-radar/src/components/RadarComponent.tsx

@@ -64,7 +64,14 @@ function matchFilter(filter?: string): (entry: RadarEntry) => boolean {
   };
 }
 
-const RadarComponent = (props: TechRadarComponentProps): JSX.Element => {
+/**
+ * Main React component of Tech Radar
+ *
+ * @remarks
+ *
+ * For advanced use cases. Typically, you want to use {@link TechRadarPage}
+ */
+function RadarComponent(props: TechRadarComponentProps) {
   const { loading, error, value: data } = useTechRadarLoader(props.id);
 
   const mapToEntries = (
@@ -106,6 +113,6 @@ const RadarComponent = (props: TechRadarComponentProps): JSX.Element => {
       )}
     </>
   );
-};
+}
 
 export default RadarComponent;

plugins/tech-radar/src/components/RadarPage.tsx

@@ -23,7 +23,7 @@ import {
 } from '@backstage/core-components';
 import { Grid, Input, makeStyles } from '@material-ui/core';
 import React from 'react';
-import { TechRadarComponentProps } from '../api';
+import { TechRadarPageProps } from '../api';
 import RadarComponent from '../components/RadarComponent';
 
 const useStyles = makeStyles(() => ({
@@ -32,18 +32,16 @@ const useStyles = makeStyles(() => ({
   },
 }));
 
-export type TechRadarPageProps = TechRadarComponentProps & {
-  title?: string;
-  subtitle?: string;
-  pageTitle?: string;
-};
-
-export const RadarPage = ({
-  title,
-  subtitle,
-  pageTitle,
-  ...props
-}: TechRadarPageProps): JSX.Element => {
+/**
+ * Main Page of Tech Radar
+ */
+export function RadarPage(props: TechRadarPageProps) {
+  const {
+    title = 'Tech Radar',
+    subtitle = 'Pick the recommended technologies for your projects',
+    pageTitle = 'Company Radar',
+    ...componentProps
+  } = props;
   const classes = useStyles();
   const [searchText, setSearchText] = React.useState('');
 
@@ -66,16 +64,10 @@ export const RadarPage = ({
         </ContentHeader>
         <Grid container spacing={3} direction="row">
           <Grid item xs={12} sm={6} md={4}>
-            <RadarComponent searchText={searchText} {...props} />
+            <RadarComponent searchText={searchText} {...componentProps} />
           </Grid>
         </Grid>
       </Content>
     </Page>
   );
-};
-
-RadarPage.defaultProps = {
-  title: 'Tech Radar',
-  subtitle: 'Pick the recommended technologies for your projects',
-  pageTitle: 'Company Radar',
-};
+}

plugins/tech-radar/src/index.ts

@@ -26,6 +26,9 @@ export {
   TechRadarPage,
 } from './plugin';
 
+/**
+ * @deprecated Use plugin extensions instead
+ */
 export { RadarPage as Router } from './components/RadarPage';
 
 /**

plugins/tech-radar/src/plugin.ts

@@ -28,6 +28,9 @@ const rootRouteRef = createRouteRef({
   title: 'Tech Radar',
 });
 
+/**
+ * Tech Radar plugin instance
+ */
 export const techRadarPlugin = createPlugin({
   id: 'tech-radar',
   routes: {
@@ -36,6 +39,13 @@ export const techRadarPlugin = createPlugin({
   apis: [createApiFactory(techRadarApiRef, new SampleTechRadarApi())],
 });
 
+/**
+ * Main Tech Radar Page
+ *
+ * @remarks
+ *
+ * Uses {@link TechRadarPageProps} as props
+ */
 export const TechRadarPage = techRadarPlugin.provide(
   createRoutableExtension({
     component: () => import('./components/RadarPage').then(m => m.RadarPage),

plugins/tech-radar/src/utils/types.ts

@@ -13,6 +13,7 @@
  * See the License for the specific language governing permissions and
  * limitations under the License.
  */
+import { MovedState } from '../api';
 
 // Parameters for a ring; its index in an array determines how close to the center this ring is.
 export type Ring = {
@@ -45,12 +46,6 @@ export type Segment = {
   random: Function;
 };
 
-export enum MovedState {
-  Down = -1,
-  NoChange = 0,
-  Up = 1,
-}
-
 export type Entry = {
   id: string;
   index?: number;