fix(repo): Add standalonePage tag for JSDoc comments (#8524)

Author: alexisintech

.typedoc/custom-router.mjs

@@ -2,6 +2,7 @@
 import { ReflectionKind } from 'typedoc';
 import { MemberRouter } from 'typedoc-plugin-markdown';
 
+import { isInlineModifierWithoutStandalonePage } from './standalone-page-tag.mjs';
 import { REFERENCE_OBJECT_PAGE_SYMBOLS } from './reference-objects.mjs';
 
 /** @type {Set<string>} */
@@ -58,15 +59,11 @@ class ClerkRouter extends MemberRouter {
         }
 
         /**
-         * `@inline` marks types that should be expanded at use sites, not documented as their own page.
+         * `@inline` marks types that should be expanded at use sites, not documented as their own page unless `@standalonePage` is also set (see `standalone-page-tag.mjs`).
          * TypeDoc still assigns `fullUrls` for exported aliases, so we also strip links in the theme's `referenceType` partial (`custom-theme.mjs`).
          */
         const model = page.model;
-        if (
-          model &&
-          'comment' in model &&
-          /** @type {{ comment?: import('typedoc').Comment | undefined }} */ (model).comment?.hasModifier('@inline')
-        ) {
+        if (model && isInlineModifierWithoutStandalonePage(/** @type {import('typedoc').Reflection} */ (model))) {
           return false;
         }
 

.typedoc/custom-theme.mjs

@@ -11,6 +11,7 @@ import { removeLineBreaks } from '../node_modules/typedoc-plugin-markdown/dist/l
 import { TypeDeclarationVisibility } from '../node_modules/typedoc-plugin-markdown/dist/options/maps.js';
 
 import { applyTodoStrippingToComment } from './comment-utils.mjs';
+import { isInlineModifierWithoutStandalonePage } from './standalone-page-tag.mjs';
 import { REFERENCE_OBJECTS_LIST } from './reference-objects.mjs';
 
 export { REFERENCE_OBJECTS_LIST };
@@ -802,7 +803,7 @@ function renderMergedIntersectionDeclaration(ctx, model, opts, mergedChildren, s
   }
   if (model.comment) {
     md.push(
-      superPartials.comment(model.comment, {
+      ctx.partials.comment(model.comment, {
         headingLevel,
         showSummary: true,
         showTags: false,
@@ -821,7 +822,7 @@ function renderMergedIntersectionDeclaration(ctx, model, opts, mergedChildren, s
 
   if (model.comment) {
     md.push(
-      superPartials.comment(model.comment, {
+      ctx.partials.comment(model.comment, {
         headingLevel,
         showSummary: false,
         showTags: true,
@@ -1060,9 +1061,9 @@ class ClerkMarkdownThemeContext extends MarkdownThemeContext {
         );
       },
       /**
-       * Stock `comments.comment` prints every {@link Comment.modifierTags} as **`TitleCase`** before the summary.
-       * `@inline` / `@inlineType` are router/type hints only; `@experimental` is SDK-only guidance — none of these
-       * must appear in property tables or prose.
+       * Stock `comments.comment` prints every {@link Comment.modifierTags} as **`TitleCase`** before the summary
+       * (it does not consult `notRenderedTags`; that option only filters block tags). `@inline` / `@inlineType` are
+       * router/type hints; `@experimental` is SDK-only guidance — none of these must appear in property tables or prose.
        *
        * @param {import('typedoc').Comment} model
        * @param {Parameters<typeof superPartials.comment>[1]} [options]
@@ -1072,7 +1073,7 @@ class ClerkMarkdownThemeContext extends MarkdownThemeContext {
           return superPartials.comment.call(this, model, options);
         }
         const modelToRender = applyTodoStrippingToComment(model) ?? model;
-        const hidden = new Set(['@inline', '@inlineType', '@experimental']);
+        const hidden = new Set(['@inline', '@inlineType', '@experimental', '@standalonePage']);
         const modTags = Array.from(modelToRender.modifierTags ?? []);
         if (modTags.some(/** @param {string} t */ t => hidden.has(t))) {
           const clone = Object.assign(Object.create(Object.getPrototypeOf(modelToRender)), modelToRender, {
@@ -1089,12 +1090,12 @@ class ClerkMarkdownThemeContext extends MarkdownThemeContext {
        */
       declarationTitle: () => '',
       /**
-       * TypeDoc's default links every {@link ReferenceType} to a URL. Types marked `@inline` are expanded at use sites and (via the router) have no standalone page — linking produces broken relative `.mdx` paths in extracted method docs. Render the **aliased type** (RHS) so literals and unions show as `'phone_code'`, not `PhoneCodeStrategy`.
+       * TypeDoc's default links every {@link ReferenceType} to a URL. Types marked `@inline` are expanded at use sites and (via the router) have no standalone page — linking produces broken relative `.mdx` paths in extracted method docs. Render the **aliased type** (RHS) so literals and unions show as `'phone_code'`, not `PhoneCodeStrategy`, unless `@standalonePage` is set (`standalone-page-tag.mjs`).
        *
        * @param {import('typedoc').ReferenceType} model
        */
       referenceType: model => {
-        if (model.reflection?.comment?.hasModifier('@inline')) {
+        if (isInlineModifierWithoutStandalonePage(model.reflection)) {
           const decl = /** @type {import('typedoc').DeclarationReflection} */ (model.reflection);
           // Generic instantiation, e.g. `Fn<Args>` — let `someType` apply type arguments.
           if (model.typeArguments?.length) {

.typedoc/extract-methods.mjs

@@ -32,6 +32,7 @@ import {
   applyRelativeLinkReplacements,
   stripReferenceObjectPropertiesSection,
 } from './custom-plugin.mjs';
+import { isInlineModifierWithoutStandalonePage } from './standalone-page-tag.mjs';
 import { prepareMarkdownRenderer } from './prepare-markdown-renderer.mjs';
 import { applyTodoStrippingToComment } from './comment-utils.mjs';
 import { REFERENCE_OBJECTS_LIST, REFERENCE_OBJECT_CONFIG } from './reference-objects.mjs';
@@ -1048,7 +1049,7 @@ function unwrapOptionalParamType(t) {
 
 /**
  * When TypeDoc renders a parameter type as a markdown link to another generated `.mdx` file, that type has a dedicated page — omit nested `param?.prop` rows so readers follow the type link instead.
- * `@inline` aliases are expanded by the theme and do not link to a standalone page.
+ * `@inline` aliases are expanded by the theme and do not link to a standalone page unless `@standalonePage` is set (`standalone-page-tag.mjs`).
  *
  * @param {import('typedoc').SomeType | undefined} t
  * @param {import('typedoc-plugin-markdown').MarkdownThemeContext} ctx
@@ -1060,7 +1061,7 @@ function parameterTypeLinksToStandaloneMdxPage(t, ctx) {
   }
   if (bare.type === 'reference') {
     const ref = /** @type {import('typedoc').ReferenceType} */ (bare);
-    if (ref.reflection?.comment?.hasModifier('@inline')) {
+    if (isInlineModifierWithoutStandalonePage(ref.reflection)) {
       return false;
     }
   }

.typedoc/standalone-page-tag.mjs

@@ -0,0 +1,24 @@
+// @ts-check
+
+/**
+ * Modifier tag: keep a dedicated `.mdx` page even when `@inline` is present (TypeDoc + our router otherwise drop inline-marked declarations; the theme also expands references instead of linking).
+ */
+export const STANDALONE_PAGE_MODIFIER_TAG = '@standalonePage';
+
+/**
+ * @param {import('typedoc').Reflection | undefined} reflection
+ * @returns {boolean} True when `@inline` should suppress a standalone page / force in-place expansion.
+ */
+export function isInlineModifierWithoutStandalonePage(reflection) {
+  const comment =
+    reflection && 'comment' in reflection
+      ? /** @type {{ comment?: import('typedoc').Comment | undefined }} */ (reflection).comment
+      : undefined;
+  if (!comment?.hasModifier('@inline')) {
+    return false;
+  }
+  if (comment.hasModifier(STANDALONE_PAGE_MODIFIER_TAG)) {
+    return false;
+  }
+  return true;
+}

packages/shared/src/react/hooks/createBillingPaginatedHook.tsx

@@ -25,28 +25,28 @@ type BillingHookConfig<TResource extends ClerkResource, TParams extends PagesOrI
 
 /**
  * @interface
+ * @standalonePage
  */
-export interface HookParams
-  extends PaginatedHookConfig<
-    PagesOrInfiniteOptions & {
-      /**
-       * If `true`, a request will be triggered when the hook is mounted.
-       *
-       * @default true
-       */
-      enabled?: boolean;
-      /**
-       * On `cache` mode, no request will be triggered when the hook is mounted and the data will be fetched from the cache.
-       *
-       * @default undefined
-       *
-       * @hidden
-       *
-       * @experimental
-       */
-      __experimental_mode?: 'cache';
-    }
-  > {
+export interface HookParams extends PaginatedHookConfig<
+  PagesOrInfiniteOptions & {
+    /**
+     * If `true`, a request will be triggered when the hook is mounted.
+     *
+     * @default true
+     */
+    enabled?: boolean;
+    /**
+     * On `cache` mode, no request will be triggered when the hook is mounted and the data will be fetched from the cache.
+     *
+     * @default undefined
+     *
+     * @hidden
+     *
+     * @experimental
+     */
+    __experimental_mode?: 'cache';
+  }
+> {
   /**
    * Specifies whether to fetch for the current user or Organization.
    *

packages/shared/src/react/types.ts

@@ -85,6 +85,7 @@ export type PaginatedResourcesWithDefault<T> = {
 
 /**
  * @inline
+ * @standalonePage
  */
 export type PaginatedHookConfig<T> = T & {
   /**

turbo.json

@@ -345,7 +345,8 @@
         ".typedoc/reference-objects.mjs",
         ".typedoc/comment-utils.mjs",
         ".typedoc/extract-methods.mjs",
-        ".typedoc/extract-returns-and-params.mjs"
+        ".typedoc/extract-returns-and-params.mjs",
+        ".typedoc/standalone-page-tag.mjs"
       ],
       "outputs": [".typedoc/**"],
       "outputLogs": "new-only"

typedoc.config.mjs

@@ -91,6 +91,8 @@ const config = {
     /** Parsed for router/theme; must not appear as a doc section (otherwise renders as **Inline**). */
     '@inline',
     '@inlineType',
+    /** Opts into a dedicated reference page despite `@inline` (see `.typedoc/standalone-page-tag.mjs`). */
+    '@standalonePage',
   ],
   packageOptions: {
     includeVersion: false,
@@ -114,11 +116,15 @@ const config = {
       /** Type-only / router hints; not user-facing prose (see `notRenderedTags`). */
       '@inline',
       '@inlineType',
+      /** With `@inline`, still emit a standalone `.mdx` page (see `.typedoc/standalone-page-tag.mjs`). */
+      '@standalonePage',
     ],
     /**
-     * Stops TypeDoc from generating standalone pages for inline types.
+     * Keep `@inline` / `@inlineType` / `@standalonePage` in the model so the custom router and theme can read them.
      */
-    excludeTags: OptionDefaults.excludeTags.filter(tag => tag !== '@inline' && tag !== '@inlineType'),
+    excludeTags: OptionDefaults.excludeTags.filter(
+      tag => tag !== '@inline' && tag !== '@inlineType' && tag !== '@standalonePage',
+    ),
     exclude: ['src/**/*.test.ts', 'src/**/*.test.tsx'],
     readme: 'none',
     disableGit: true,