chore: working through the api-report of scaffolder-backend

Signed-off-by: blam <ben@blam.sh>

.changeset/lucky-kangaroos-sneeze.md

@@ -0,0 +1,6 @@
+---
+'@backstage/plugin-scaffolder-backend': patch
+'@backstage/plugin-scaffolder-common': patch
+---
+
+Adding some documentation for exported things

plugins/scaffolder-backend/api-report.md

@@ -49,15 +49,10 @@ export const createBuiltinActions: (
 
 // @public
 export interface CreateBuiltInActionsOptions {
-  // (undocumented)
   additionalTemplateFilters?: Record<string, TemplateFilter>;
-  // (undocumented)
   catalogClient: CatalogApi;
-  // (undocumented)
   config: Config;
-  // (undocumented)
   integrations: ScmIntegrations;
-  // (undocumented)
   reader: UrlReader;
 }
 
@@ -142,19 +137,16 @@ export function createGithubActionsDispatchAction(options: {
   token?: string | undefined;
 }>;
 
-// @public (undocumented)
+// @public
 export interface CreateGithubPullRequestActionOptions {
-  // (undocumented)
   clientFactory?: (
     input: CreateGithubPullRequestClientFactoryInput,
   ) => Promise<OctokitWithPullRequestPluginClient>;
-  // (undocumented)
   githubCredentialsProvider?: GithubCredentialsProvider;
-  // (undocumented)
   integrations: ScmIntegrationRegistry;
 }
 
-// @public (undocumented)
+// @public
 export type CreateGithubPullRequestClientFactoryInput = {
   integrations: ScmIntegrationRegistry;
   githubCredentialsProvider?: GithubCredentialsProvider;
@@ -278,7 +270,7 @@ export const createPublishGitlabMergeRequestAction: (options: {
   token?: string | undefined;
 }>;
 
-// @public (undocumented)
+// @public
 export function createRouter(options: RouterOptions): Promise<express.Router>;
 
 // @public
@@ -298,11 +290,8 @@ export type CreateWorkerOptions = {
 
 // @public
 export interface CurrentClaimedTask {
-  // (undocumented)
   secrets?: TaskSecrets;
-  // (undocumented)
   spec: TaskSpec;
-  // (undocumented)
   taskId: string;
 }
 

plugins/scaffolder-backend/src/scaffolder/actions/builtin/createBuiltinActions.ts

@@ -54,10 +54,26 @@ import { TemplateAction } from '../types';
  * @public
  */
 export interface CreateBuiltInActionsOptions {
+  /**
+   * The {@link @backstage/backend-common#UrlReader} interface that will be used in the default actions.
+   */
   reader: UrlReader;
+  /**
+   * The {@link @backstage/integrations#ScmIntegrations} that will be used in the default actions.
+   */
   integrations: ScmIntegrations;
+  /**
+   * The {@link @backstage/catalog-client#CatalogApi} that will be used in the default actions.
+   */
   catalogClient: CatalogApi;
+  /**
+   * The {@link @backstage/config#Config} that will be used in the default actions.
+   */
   config: Config;
+  /**
+   * Additional custom filters that will be passed to the nunjucks template engine for use in
+   * Template Manifests and also template skeleton files when using `fetch:template`.
+   */
   additionalTemplateFilters?: Record<string, TemplateFilter>;
 }
 

plugins/scaffolder-backend/src/scaffolder/actions/builtin/publish/githubPullRequest.ts

@@ -41,7 +41,10 @@ export interface OctokitWithPullRequestPluginClient {
   } | null>;
 }
 
-/** @public */
+/**
+ * The options passed to the client factory function.
+ * @public
+ */
 export type CreateGithubPullRequestClientFactoryInput = {
   integrations: ScmIntegrationRegistry;
   githubCredentialsProvider?: GithubCredentialsProvider;
@@ -74,10 +77,22 @@ export const defaultClientFactory = async ({
   return new OctokitPR(octokitOptions);
 };
 
-/** @public */
+/**
+ * The options passed to {@link createPublishGithubPullRequestAction} method
+ * @public
+ */
 export interface CreateGithubPullRequestActionOptions {
+  /**
+   * An instance of {@link @backstage/integration#ScmIntegrationRegistry} that will be used in the action.
+   */
   integrations: ScmIntegrationRegistry;
+  /**
+   * An instance of {@link @backstage/integration#GithubCredentialsProvider} that will be used to get credentials for the action.
+   */
   githubCredentialsProvider?: GithubCredentialsProvider;
+  /**
+   * A method to return the Octokit client with the Pull Request Plugin.
+   */
   clientFactory?: (
     input: CreateGithubPullRequestClientFactoryInput,
   ) => Promise<OctokitWithPullRequestPluginClient>;

plugins/scaffolder-backend/src/scaffolder/tasks/StorageTaskBroker.ts

@@ -115,8 +115,17 @@ export class TaskManager implements TaskContext {
  * @public
  */
 export interface CurrentClaimedTask {
+  /**
+   * The TaskSpec of the current claimed task.
+   */
   spec: TaskSpec;
+  /**
+   * The uuid of the current claimed task.
+   */
   taskId: string;
+  /**
+   * The secrets that are stored with the task.
+   */
   secrets?: TaskSecrets;
 }
 
@@ -135,6 +144,9 @@ export class StorageTaskBroker implements TaskBroker {
   ) {}
   private deferredDispatch = defer();
 
+  /**
+   * @inheritdoc
+   */
   async claim(): Promise<TaskContext> {
     for (;;) {
       const pendingTask = await this.storage.claimTask();
@@ -154,6 +166,9 @@ export class StorageTaskBroker implements TaskBroker {
     }
   }
 
+  /**
+   * @inheritdoc
+   */
   async dispatch(
     options: TaskBrokerDispatchOptions,
   ): Promise<{ taskId: string }> {
@@ -164,10 +179,16 @@ export class StorageTaskBroker implements TaskBroker {
     };
   }
 
+  /**
+   * @inheritdoc
+   */
   async get(taskId: string): Promise<SerializedTask> {
     return this.storage.getTask(taskId);
   }
 
+  /**
+   * @inheritdoc
+   */
   event$(options: {
     taskId: string;
     after?: number;
@@ -197,6 +218,9 @@ export class StorageTaskBroker implements TaskBroker {
     });
   }
 
+  /**
+   * @inheritdoc
+   */
   async vacuumTasks(options: { timeoutS: number }): Promise<void> {
     const { tasks } = await this.storage.listStaleTasks(options);
     await Promise.all(

plugins/scaffolder-backend/src/service/router.ts

@@ -62,7 +62,10 @@ function isSupportedTemplate(entity: TemplateEntityV1beta3) {
   return entity.apiVersion === 'scaffolder.backstage.io/v1beta3';
 }
 
-/** @public */
+/**
+ * A method to create a router for the scaffolder backend plugin.
+ * @public
+ */
 export async function createRouter(
   options: RouterOptions,
 ): Promise<express.Router> {