feat(typedoc): document a type on the page of the one member using it

A type with members that only one member with a page of its own uses, as
`treeshake?: boolean | TreeshakeOptions` uses `TreeshakeOptions`, is
documented on that member's page, as `buildOptions.treeshake.annotations`
and so on. The type's own page links there, and so do links to it and the
type map; the page list leaves it out. The plugin did this before, and
links into such options (`InputOptions.treeshake#annotations`) rely on it.

Assisted-by: Claude Opus 5.5 <noreply@anthropic.com>

Author: ovflowd

packages/typedoc/README.md

@@ -43,9 +43,9 @@ The output directory receives, following TypeDoc's own layout:
 
 - A page per module and namespace (`modules/plugins.md`), listing its exports.
 - A page per exported class, interface, enum, type alias, function and variable: `classes/Watcher.md`, `functions/build.md`, …
-- A page per member of the types in `docKitMemberPages`: `interfaces/BuildOptions.input.md`, …
+- A page per member of the types in `docKitMemberPages`: `interfaces/BuildOptions.input.md`, … A type only one of these members uses (`boolean | TreeshakeOptions`) is documented on its page, and the type's own page links there.
 - `type-map.json`, mapping type names to their pages, for doc-kit's `typeMap` to link `{Type}` annotations with.
-- `pages.json`, listing every page (full name, kind, URL and `@category`) for the site to build its navigation from.
+- `pages.json`, listing every page (full name, kind, URL and `@category`) for the site to build its navigation from, but those of types documented on a member's page.
 
 `docKitUrlAdapter` adapts these URLs, to keep the URLs of a previous site working. Links between pages are relative `.md` links, which doc-kit resolves. Source links are relative to TypeDoc's `basePath` (or `displayBasePath`); set it to the root of your repository.
 

packages/typedoc/src/__tests__/fixtures/index.ts

@@ -27,6 +27,19 @@ export interface BuildOptions {
    * @experimental
    */
   output?: Readonly<{ dir: string; format?: Format }>;
+  /**
+   * How to tree-shake, keeping
+   * {@link TreeshakeOptions.annotations | annotated} calls or not.
+   */
+  treeshake?: boolean | TreeshakeOptions;
+}
+
+/**
+ * Options of tree-shaking.
+ */
+export interface TreeshakeOptions {
+  /** Whether to keep the calls annotated as pure. */
+  annotations?: boolean;
 }
 
 /**

packages/typedoc/src/__tests__/index.test.mjs.snapshot

@@ -74,13 +74,16 @@ export const generate = async (app, directory, project) => {
 
   if (typeMapFile) {
     writes.push(
-      writeJSON(join(directory, typeMapFile), typeMap(pages, basePath))
+      writeJSON(join(directory, typeMapFile), typeMap(router, pages, basePath))
     );
   }
 
   if (pageListFile) {
     writes.push(
-      writeJSON(join(directory, pageListFile), pageList(pages, basePath))
+      writeJSON(
+        join(directory, pageListFile),
+        pageList(router, pages, basePath)
+      )
     );
   }
 

packages/typedoc/src/generate.mjs

@@ -18,13 +18,15 @@ export const receiverOf = (app, owner) =>
 /**
  * The name an entry is documented by: `build` for an export, then
  * `new Watcher`, `Watcher.create`, `watcher.close`, or
- * `buildOptions.output.dir` for the members of a type.
+ * `buildOptions.output.dir` for the members of a type, and
+ * `buildOptions.treeshake.annotations` for those of a type documented on a
+ * member's page.
  *
- * @param {import('typedoc').Application} app
+ * @param {import('../utils/router.mjs').DocKitRouter} router
  * @param {import('typedoc').Reflection} reflection
  * @returns {string}
  */
-export const entryName = (app, reflection) => {
+export const entryName = (router, reflection) => {
   // The members of an object type belong to what has that type
   const parent = reflection.parent?.kindOf(ReflectionKind.TypeLiteral)
     ? reflection.parent.parent
@@ -45,8 +47,17 @@ export const entryName = (app, reflection) => {
     return `${parent.name}.${reflection.name}`;
   }
 
+  const documentedOn = router.inlined.get(parent);
+
+  if (documentedOn) {
+    return `${entryName(router, documentedOn)}.${reflection.name}`;
+  }
+
   const isOwner = parent.parent?.kindOf(ReflectionKind.ExportContainer);
-  const receiver = isOwner ? receiverOf(app, parent) : entryName(app, parent);
+
+  const receiver = isOwner
+    ? receiverOf(router.application, parent)
+    : entryName(router, parent);
 
   return `${receiver}.${reflection.name}`;
 };
@@ -116,12 +127,12 @@ export const callHeading = (name, signature) => {
 /**
  * The heading of an entry: its call, when given a signature, or its name.
  *
- * @param {import('typedoc').Application} app
+ * @param {import('../utils/router.mjs').DocKitRouter} router
  * @param {import('typedoc').Reflection} reflection
  * @param {import('typedoc').SignatureReflection} [signature]
  */
-export const entryHeading = (app, reflection, signature) => {
-  const name = entryName(app, reflection);
+export const entryHeading = (router, reflection, signature) => {
+  const name = entryName(router, reflection);
 
   if (!signature) {
     return code(name);

packages/typedoc/src/render/entries.mjs

@@ -18,6 +18,7 @@ import {
   membersOf,
   nestedObject,
   objectDeclaration,
+  referencedType,
   signaturesOf,
   typeOf,
 } from '../utils/reflections.mjs';
@@ -55,7 +56,7 @@ export const renderSignature = (
 
   return renderEntry(context, {
     depth,
-    label: entryHeading(context.app, declaration, signature),
+    label: entryHeading(context.router, declaration, signature),
     reflection: declaration,
     comment: signature.comment ?? declaration.comment,
     signature,
@@ -66,7 +67,25 @@ export const renderSignature = (
 };
 
 /**
- * The entry of a property, with the properties of an object type nested.
+ * The members documented under a property: those of its object type, or of
+ * the type documented on its page (`TreeshakeOptions` on `treeshake`'s).
+ *
+ * @param {import('../types').Context} context
+ * @param {import('typedoc').DeclarationReflection} member
+ */
+const nestedMembers = ({ router }, member) => {
+  const type = typeOf(member);
+  const named = referencedType(type);
+
+  if (named && router.inlined.get(named) === member) {
+    return membersOf(named);
+  }
+
+  return nestedObject(type)?.children ?? [];
+};
+
+/**
+ * The entry of a property, with the members of its type nested.
  *
  * @param {import('../types').Context} context
  * @param {import('typedoc').DeclarationReflection} member
@@ -76,14 +95,14 @@ export const renderSignature = (
 const renderProperty = (context, member, depth, extras = {}) => {
   const lines = renderEntry(context, {
     depth,
-    label: entryHeading(context.app, member),
+    label: entryHeading(context.router, member),
     reflection: member,
     comment: commentOf(member),
     items: [typeItem(context, member)],
     ...extras,
   });
 
-  for (const child of nestedObject(typeOf(member))?.children ?? []) {
+  for (const child of nestedMembers(context, member)) {
     lines.push(...renderMember(context, child, depth + 1));
   }
 

packages/typedoc/src/render/members.mjs

@@ -3,7 +3,7 @@
 import { ReflectionKind } from 'typedoc';
 
 import { splitSummary } from './comments.mjs';
-import { renderEntry } from './entries.mjs';
+import { entryName, renderEntry } from './entries.mjs';
 import { typeItem } from './lists.mjs';
 import {
   renderEvents,
@@ -75,6 +75,26 @@ const pageEntry = (context, reflection, entry = {}) =>
     ...entry,
   });
 
+/**
+ * A type documented on the page of the member using it: its description, and
+ * a link there.
+ *
+ * @param {import('../types').Context} context
+ * @param {import('typedoc').DeclarationReflection} declaration
+ * @param {import('typedoc').DeclarationReflection} member
+ */
+const inlinedTypePage = (context, declaration, member) => {
+  const name = code(entryName(context.router, member));
+  const link = context.router.linkTo(context.page, member);
+
+  return pageEntry(context, declaration, {
+    notes: [
+      ...importedFrom(context, declaration),
+      `Documented with [${name}](${link}).`,
+    ],
+  });
+};
+
 /**
  * A module or namespace: a list of its exports, by group.
  *
@@ -180,6 +200,12 @@ const typePage = (context, declaration) => [
  * @returns {string[]}
  */
 export const renderPage = (context, reflection) => {
+  const member = context.router.inlined.get(reflection);
+
+  if (member) {
+    return inlinedTypePage(context, reflection, member);
+  }
+
   if (reflection.kindOf(ReflectionKind.SomeModule)) {
     return containerPage(context, reflection);
   }

packages/typedoc/src/render/pages.mjs

@@ -14,29 +14,39 @@ const inputPath = (basePath, url) =>
 
 /**
  * Type names mapped to the pages documenting them, for doc-kit's `typeMap`
- * to link `{Type}` annotations with.
+ * to link `{Type}` annotations with: their own, or the page of the member
+ * documenting them.
  *
+ * @param {import('./router.mjs').DocKitRouter} router
  * @param {Array<import('typedoc').PageDefinition>} pages
  * @param {string} basePath
  */
-export const typeMap = (pages, basePath) =>
+export const typeMap = (router, pages, basePath) =>
   Object.fromEntries(
     pages
       .filter(({ model }) => model.kindOf(ReflectionKind.TypeReferenceTarget))
-      .map(({ model, url }) => [model.name, inputPath(basePath, url)])
+      .map(({ model }) => {
+        const home = router.inlined.get(model) ?? model;
+
+        return [model.name, inputPath(basePath, router.getFullUrl(home))];
+      })
   );
 
 /**
- * Every page, for the site to build its navigation from.
+ * Every page, for the site to build its navigation from, but those of the
+ * types documented on a member's page, which link there.
  *
+ * @param {import('./router.mjs').DocKitRouter} router
  * @param {Array<import('typedoc').PageDefinition>} pages
  * @param {string} basePath
  * @returns {import('../types').PageEntry[]}
  */
-export const pageList = (pages, basePath) =>
-  pages.map(({ model, url }) => ({
-    name: model.getFriendlyFullName(),
-    kind: ReflectionKind[model.kind],
-    url: `/${inputPath(basePath, url)}`,
-    category: categoryOf(model),
-  }));
+export const pageList = (router, pages, basePath) =>
+  pages
+    .filter(({ model }) => !router.inlined.has(model))
+    .map(({ model, url }) => ({
+      name: model.getFriendlyFullName(),
+      kind: ReflectionKind[model.kind],
+      url: `/${inputPath(basePath, url)}`,
+      category: categoryOf(model),
+    }));

packages/typedoc/src/utils/manifest.mjs

@@ -60,6 +60,22 @@ export const nestedObject = type => {
   return objects.length === 1 ? objects[0] : undefined;
 };
 
+/**
+ * The declaration of the project a type refers to, alone or as the one
+ * reference of a union (`boolean | TreeshakeOptions`).
+ *
+ * @param {import('typedoc').SomeType | undefined} type
+ */
+export const referencedType = type => {
+  const types = type?.type === 'union' ? type.types : [type];
+
+  const declarations = types
+    .map(part => referencedDeclaration(unwrap(part)))
+    .filter(Boolean);
+
+  return declarations.length === 1 ? declarations[0] : undefined;
+};
+
 /**
  * The call signatures of a function, method, callable interface, or a
  * declaration whose type is one of them, named or not: a variable typed with