update some backend system doc comments

Signed-off-by: Fredrik Adelöw <freben@gmail.com>

packages/backend-plugin-api/api-report.md

@@ -22,11 +22,9 @@ export interface BackendFeature {
   register(reg: BackendRegistrationPoints): void;
 }
 
-// @public (undocumented)
+// @public
 export interface BackendModuleConfig {
-  // (undocumented)
   moduleId: string;
-  // (undocumented)
   pluginId: string;
   // (undocumented)
   register(
@@ -34,9 +32,8 @@ export interface BackendModuleConfig {
   ): void;
 }
 
-// @public (undocumented)
+// @public
 export interface BackendPluginConfig {
-  // (undocumented)
   id: string;
   // (undocumented)
   register(reg: BackendRegistrationPoints): void;
@@ -116,12 +113,12 @@ export function createBackendModule<TOptions extends [options?: object] = []>(
   config: BackendModuleConfig | ((...params: TOptions) => BackendModuleConfig),
 ): (...params: TOptions) => BackendFeature;
 
-// @public (undocumented)
+// @public
 export function createBackendPlugin<TOptions extends [options?: object] = []>(
   config: BackendPluginConfig | ((...params: TOptions) => BackendPluginConfig),
 ): (...params: TOptions) => BackendFeature;
 
-// @public (undocumented)
+// @public
 export function createExtensionPoint<T>(
   config: ExtensionPointConfig,
 ): ExtensionPoint<T>;
@@ -248,9 +245,8 @@ export type ExtensionPoint<T> = {
   $$ref: 'extension-point';
 };
 
-// @public (undocumented)
+// @public
 export interface ExtensionPointConfig {
-  // (undocumented)
   id: string;
 }
 
@@ -476,13 +472,13 @@ export interface ServiceRefConfig<TService, TScope extends 'root' | 'plugin'> {
   scope?: TScope;
 }
 
-// @public (undocumented)
+// @public
 export interface SharedBackendEnvironment {
   // (undocumented)
   $$type: 'SharedBackendEnvironment';
 }
 
-// @public (undocumented)
+// @public
 export interface SharedBackendEnvironmentConfig {
   // (undocumented)
   services?: ServiceFactoryOrFunction[];

packages/backend-plugin-api/src/wiring/createSharedEnvironment.ts

@@ -16,35 +16,47 @@
 
 import { ServiceFactory, ServiceFactoryOrFunction } from '../services';
 
-/** @public */
+/**
+ * The configuration options passed to {@link createSharedEnvironment}.
+ *
+ * @public
+ */
 export interface SharedBackendEnvironmentConfig {
   services?: ServiceFactoryOrFunction[];
 }
 
-// This type is opaque in order to allow for future API evolution without
-// cluttering the external API. For example we might want to add support
-// for more powerful callback based backend modifications.
-//
-// By making this opaque we also ensure that the type doesn't become an input
-// type that we need to care about, as it would otherwise be possible to pass
-// a custom environment definition to `createBackend`, which we don't want.
 /**
+ * An opaque type that represents the contents of a shared backend environment.
+ *
  * @public
  */
 export interface SharedBackendEnvironment {
   $$type: 'SharedBackendEnvironment';
+
+  // NOTE: This type is opaque in order to allow for future API evolution without
+  // cluttering the external API. For example we might want to add support
+  // for more powerful callback based backend modifications.
+  //
+  // By making this opaque we also ensure that the type doesn't become an input
+  // type that we need to care about, as it would otherwise be possible to pass
+  // a custom environment definition to `createBackend`, which we don't want.
 }
 
 /**
- * This type is NOT supposed to be used by anyone except internally by the backend-app-api package.
- * @internal */
+ * This type is NOT supposed to be used by anyone except internally by the
+ * backend-app-api package.
+ *
+ * @internal
+ */
 export interface InternalSharedBackendEnvironment {
   version: 'v1';
   services?: ServiceFactory[];
 }
 
 /**
- * Creates a shared backend environment which can be used to create multiple backends
+ * Creates a shared backend environment which can be used to create multiple
+ * backends.
+ *
  * @public
  */
 export function createSharedEnvironment<

packages/backend-plugin-api/src/wiring/factories.ts

@@ -20,12 +20,28 @@ import {
   ExtensionPoint,
 } from './types';
 
-/** @public */
+/**
+ * The configuration options passed to {@link createExtensionPoint}.
+ *
+ * @public
+ * @see {@link https://backstage.io/docs/backend-system/architecture/extension-points | The architecture of extension points}
+ * @see {@link https://backstage.io/docs/backend-system/architecture/naming-patterns | Recommended naming patterns}
+ */
 export interface ExtensionPointConfig {
+  /**
+   * The ID of this extension point.
+   *
+   * @see {@link https://backstage.io/docs/backend-system/architecture/naming-patterns | Recommended naming patterns}
+   */
   id: string;
 }
 
-/** @public */
+/**
+ * Creates a new backend extension point.
+ *
+ * @public
+ * @see {@link https://backstage.io/docs/backend-system/architecture/extension-points | The architecture of extension points}
+ */
 export function createExtensionPoint<T>(
   config: ExtensionPointConfig,
 ): ExtensionPoint<T> {
@@ -41,13 +57,30 @@ export function createExtensionPoint<T>(
   };
 }
 
-/** @public */
+/**
+ * The configuration options passed to {@link createBackendPlugin}.
+ *
+ * @public
+ * @see {@link https://backstage.io/docs/backend-system/architecture/plugins | The architecture of plugins}
+ * @see {@link https://backstage.io/docs/backend-system/architecture/naming-patterns | Recommended naming patterns}
+ */
 export interface BackendPluginConfig {
+  /**
+   * The ID of this plugin.
+   *
+   * @see {@link https://backstage.io/docs/backend-system/architecture/naming-patterns | Recommended naming patterns}
+   */
   id: string;
   register(reg: BackendRegistrationPoints): void;
 }
 
-/** @public */
+/**
+ * Creates a new backend plugin.
+ *
+ * @public
+ * @see {@link https://backstage.io/docs/backend-system/architecture/plugins | The architecture of plugins}
+ * @see {@link https://backstage.io/docs/backend-system/architecture/naming-patterns | Recommended naming patterns}
+ */
 export function createBackendPlugin<TOptions extends [options?: object] = []>(
   config: BackendPluginConfig | ((...params: TOptions) => BackendPluginConfig),
 ): (...params: TOptions) => BackendFeature {
@@ -58,9 +91,23 @@ export function createBackendPlugin<TOptions extends [options?: object] = []>(
   return () => config;
 }
 
-/** @public */
+/**
+ * The configuration options passed to {@link createBackendModule}.
+ *
+ * @public
+ * @see {@link https://backstage.io/docs/backend-system/architecture/modules | The architecture of modules}
+ * @see {@link https://backstage.io/docs/backend-system/architecture/naming-patterns | Recommended naming patterns}
+ */
 export interface BackendModuleConfig {
+  /**
+   * The ID of this plugin.
+   *
+   * @see {@link https://backstage.io/docs/backend-system/architecture/naming-patterns | Recommended naming patterns}
+   */
   pluginId: string;
+  /**
+   * Should exactly match the `id` of the plugin that the module extends.
+   */
   moduleId: string;
   register(
     reg: Omit<BackendRegistrationPoints, 'registerExtensionPoint'>,
@@ -71,15 +118,8 @@ export interface BackendModuleConfig {
  * Creates a new backend module for a given plugin.
  *
  * @public
- *
- * @remarks
- *
- * The `moduleId` should be equal to the module-specific suffix of the exported name, such
- * that the full name is `pluginId + "Module" + ModuleId`. For example, a GitHub entity
- * provider module for the `catalog` plugin might have the module ID `'githubEntityProvider'`,
- * and the full exported name would be `catalogModuleGithubEntityProvider`.
- *
- * The `pluginId` should exactly match the `id` of the plugin that the module extends.
+ * @see {@link https://backstage.io/docs/backend-system/architecture/modules | The architecture of modules}
+ * @see {@link https://backstage.io/docs/backend-system/architecture/naming-patterns | Recommended naming patterns}
  */
 export function createBackendModule<TOptions extends [options?: object] = []>(
   config: BackendModuleConfig | ((...params: TOptions) => BackendModuleConfig),