From bd55cc941f802b331778bc9064b61b5caa8b8078 Mon Sep 17 00:00:00 2001
From: Patrik Oldsberg <poldsberg@gmail.com>
Date: Thu, 7 Aug 2025 13:59:13 +0200
Subject: [PATCH] frontend-plugin-api: TsDoc for createFrontendModule

Signed-off-by: Patrik Oldsberg <poldsberg@gmail.com>
---
 .../src/wiring/createFrontendModule.ts        | 40 ++++++++++++++++++-
 1 file changed, 39 insertions(+), 1 deletion(-)

diff --git a/packages/frontend-plugin-api/src/wiring/createFrontendModule.ts b/packages/frontend-plugin-api/src/wiring/createFrontendModule.ts
index bece1539fa..00b569657f 100644
--- a/packages/frontend-plugin-api/src/wiring/createFrontendModule.ts
+++ b/packages/frontend-plugin-api/src/wiring/createFrontendModule.ts
@@ -45,7 +45,45 @@ export interface InternalFrontendModule extends FrontendModule {
   readonly featureFlags: FeatureFlagConfig[];
 }
 
-/** @public */
+/**
+ * Creates a new module instance that can be installed in a Backstage app.
+ *
+ * @remarks
+ *
+ * Modules are used to add or override extensions for an existing plugin. If a
+ * module provides an extension with the same ID as one provided by the plugin,
+ * the extension provided by the module will always take presedence.
+ *
+ * Every module instance is created for a specific plugin by providing the
+ * unique ID of the plugin that the module should be installed for. If that
+ * plugin is not present in the app, the module will be ignored and have no
+ * effect.
+ *
+ * For more information on how modules work, see the
+ * {@link https://backstage.io/docs/frontend-system/architecture/extension-overrides#creating-a-frontend-module | documentation for modules}
+ * in the frontend system documentation.
+ *
+ * It is recommended to name the module variable of the form `<pluginId>Module<ModuleName>`.
+ *
+ * @example
+ *
+ *```tsx
+ *import { createFrontendModule } from '@backstage/frontend-plugin-api';
+ *
+ *export const exampleModuleCustomPage = createFrontendModule({
+ *  pluginId: 'example',
+ *  extensions: [
+ *    // Overrides the default page for the 'example' plugin
+ *    PageBlueprint.make({
+ *      path: '/example',
+ *      loader: () => import('./CustomPage').then(m => <m.CustomPage />),
+ *    }),
+ *  ],
+ *});
+ *```
+ *
+ * @public
+ */
 export function createFrontendModule<
   TId extends string,
   TExtensions extends readonly ExtensionDefinition[] = [],