Merge pull request #7068 from backstage/rugvip/cleanup

plugins/todo: properly export types and avoid usage of deprecated functions

.changeset/forty-moons-boil.md

@@ -0,0 +1,5 @@
+---
+'@backstage/plugin-todo': patch
+---
+
+All types are now properly documented and exported.

plugins/todo/api-report.md

@@ -7,22 +7,84 @@
 
 import { ApiRef } from '@backstage/core-plugin-api';
 import { BackstagePlugin } from '@backstage/core-plugin-api';
+import { DiscoveryApi } from '@backstage/core-plugin-api';
 import { Entity } from '@backstage/catalog-model';
+import { IdentityApi } from '@backstage/core-plugin-api';
 
-// Warning: (ae-missing-release-tag) "EntityTodoContent" is exported by the package, but it is missing a release tag (@alpha, @beta, @public, or @internal)
-//
-// @public (undocumented)
+// @public
 export const EntityTodoContent: () => JSX.Element;
 
-// Warning: (ae-forgotten-export) The symbol "TodoApi" needs to be exported by the entry point index.d.ts
-// Warning: (ae-missing-release-tag) "todoApiRef" is exported by the package, but it is missing a release tag (@alpha, @beta, @public, or @internal)
-//
-// @public (undocumented)
+// @public
+export interface TodoApi {
+  listTodos(options: TodoListOptions): Promise<TodoListResult>;
+}
+
+// @public
 export const todoApiRef: ApiRef<TodoApi>;
 
-// Warning: (ae-missing-release-tag) "todoPlugin" is exported by the package, but it is missing a release tag (@alpha, @beta, @public, or @internal)
-//
-// @public (undocumented)
+// @public
+export class TodoClient implements TodoApi {
+  constructor(options: TodoClientOptions);
+  // (undocumented)
+  listTodos({
+    entity,
+    offset,
+    limit,
+    orderBy,
+    filters,
+  }: TodoListOptions): Promise<TodoListResult>;
+}
+
+// @public
+export interface TodoClientOptions {
+  // (undocumented)
+  discoveryApi: DiscoveryApi;
+  // (undocumented)
+  identityApi: IdentityApi;
+}
+
+// @public
+export type TodoItem = {
+  text: string;
+  tag: string;
+  author?: string;
+  viewUrl?: string;
+  lineNumber?: number;
+  repoFilePath?: string;
+};
+
+// @public
+export type TodoListFields =
+  | 'text'
+  | 'tag'
+  | 'author'
+  | 'viewUrl'
+  | 'repoFilePath';
+
+// @public
+export type TodoListOptions = {
+  entity?: Entity;
+  offset?: number;
+  limit?: number;
+  orderBy?: {
+    field: TodoListFields;
+    direction: 'asc' | 'desc';
+  };
+  filters?: {
+    field: TodoListFields;
+    value: string;
+  }[];
+};
+
+// @public
+export type TodoListResult = {
+  items: TodoItem[];
+  totalCount: number;
+  offset: number;
+  limit: number;
+};
+
+// @public
 export const todoPlugin: BackstagePlugin<{}, {}>;
 
 // (No @packageDocumentation comment for this package)

plugins/todo/src/api/TodoClient.ts

@@ -14,21 +14,31 @@
  * limitations under the License.
  */
 
-import { serializeEntityRef } from '@backstage/catalog-model';
+import { stringifyEntityRef } from '@backstage/catalog-model';
 import { ResponseError } from '@backstage/errors';
 import { TodoApi, TodoListOptions, TodoListResult } from './types';
 import { DiscoveryApi, IdentityApi } from '@backstage/core-plugin-api';
 
-interface Options {
+/**
+ * Options for creating a todo client.
+ *
+ * @public
+ */
+export interface TodoClientOptions {
   discoveryApi: DiscoveryApi;
   identityApi: IdentityApi;
 }
 
+/**
+ * An implementation of the TodoApi that talks to the todo plugin backend.
+ *
+ * @public
+ */
 export class TodoClient implements TodoApi {
   private readonly discoveryApi: DiscoveryApi;
   private readonly identityApi: IdentityApi;
 
-  constructor(options: Options) {
+  constructor(options: TodoClientOptions) {
     this.discoveryApi = options.discoveryApi;
     this.identityApi = options.identityApi;
   }
@@ -45,7 +55,7 @@ export class TodoClient implements TodoApi {
 
     const query = new URLSearchParams();
     if (entity) {
-      query.set('entity', serializeEntityRef(entity) as string);
+      query.set('entity', stringifyEntityRef(entity));
     }
     if (typeof offset === 'number') {
       query.set('offset', String(offset));

plugins/todo/src/api/index.ts

@@ -15,5 +15,12 @@
  */
 
 export { TodoClient } from './TodoClient';
+export type { TodoClientOptions } from './TodoClient';
 export { todoApiRef } from './types';
-export type { TodoApi } from './types';
+export type {
+  TodoApi,
+  TodoListOptions,
+  TodoListResult,
+  TodoItem,
+  TodoListFields,
+} from './types';

plugins/todo/src/api/types.ts

@@ -17,6 +17,11 @@
 import { Entity } from '@backstage/catalog-model';
 import { createApiRef } from '@backstage/core-plugin-api';
 
+/**
+ * TodoItem represents a single TODO comment in source code.
+ *
+ * @public
+ */
 export type TodoItem = {
   /** The contents of the TODO comment */
   text: string;
@@ -37,23 +42,43 @@ export type TodoItem = {
   repoFilePath?: string;
 };
 
-type Fields = 'text' | 'tag' | 'author' | 'viewUrl' | 'repoFilePath';
+/**
+ * Fields that can be used to filter or order todo items.
+ *
+ * @public
+ */
+export type TodoListFields =
+  | 'text'
+  | 'tag'
+  | 'author'
+  | 'viewUrl'
+  | 'repoFilePath';
 
+/**
+ * Options used to list todo items.
+ *
+ * @public
+ */
 export type TodoListOptions = {
   entity?: Entity;
   offset?: number;
   limit?: number;
   orderBy?: {
-    field: Fields;
+    field: TodoListFields;
     direction: 'asc' | 'desc';
   };
   filters?: {
-    field: Fields;
+    field: TodoListFields;
     /** Value to filter by, with '*' used as wildcard */
     value: string;
   }[];
 };
 
+/**
+ * The result of listing todos.
+ *
+ * @public
+ */
 export type TodoListResult = {
   items: TodoItem[];
   totalCount: number;
@@ -61,10 +86,25 @@ export type TodoListResult = {
   limit: number;
 };
 
+/**
+ * The API used by the todo-plugin to list todos.
+ *
+ * @public
+ */
 export interface TodoApi {
+  /**
+   * Lists todo items.
+   *
+   * @public
+   */
   listTodos(options: TodoListOptions): Promise<TodoListResult>;
 }
 
+/**
+ * ApiRef for the TodoApi.
+ *
+ * @public
+ */
 export const todoApiRef = createApiRef<TodoApi>({
   id: 'plugin.todo.api',
   description: 'Lists TODOs',

plugins/todo/src/index.ts

@@ -14,5 +14,13 @@
  * limitations under the License.
  */
 
-export { todoApiRef } from './api';
+export { todoApiRef, TodoClient } from './api';
+export type {
+  TodoApi,
+  TodoListOptions,
+  TodoListResult,
+  TodoItem,
+  TodoListFields,
+  TodoClientOptions,
+} from './api';
 export { todoPlugin, EntityTodoContent } from './plugin';

plugins/todo/src/plugin.ts

@@ -22,8 +22,11 @@ import {
   identityApiRef,
 } from '@backstage/core-plugin-api';
 
-// import { rootRouteRef } from './routes';
-
+/**
+ * The Todo plugin instance.
+ *
+ * @public
+ */
 export const todoPlugin = createPlugin({
   id: 'todo',
   apis: [
@@ -43,6 +46,11 @@ export const todoPlugin = createPlugin({
   },
 });
 
+/**
+ * An extension for displaying the list of todos on an entity page.
+ *
+ * @public
+ */
 export const EntityTodoContent = todoPlugin.provide(
   createComponentExtension({
     component: {