Skip to content

docs: clean up 'Other' category on API reference index#8627

Merged
willeastcott merged 2 commits into
mainfrom
docs/other-category-accessor-sweep
Apr 21, 2026
Merged

docs: clean up 'Other' category on API reference index#8627
willeastcott merged 2 commits into
mainfrom
docs/other-category-accessor-sweep

Conversation

@willeastcott

Copy link
Copy Markdown
Contributor

Overview

The engine's API reference index page was showing ~57 orphan entries under the "Other" category — class accessors (depthFunc, blendType, children, parent, enabled, volume, pitch, theme, maxPixelRatio, etc.) that typedoc-plugin-missing-exports was incorrectly hoisting out of their owning class into the project root. Each entry had a broken self-link to an anchor that didn't exist, and the section was pure noise on the landing page of the generated docs.

Fix

Added a Converter.EVENT_RESOLVE_END handler to the custom TypeDoc plugin (utils/typedoc/typedoc-plugin.mjs) that removes any top-level ReflectionKind.Accessor children from the project root after TypeDoc resolution completes.

app.converter.on(Converter.EVENT_RESOLVE_END, (context) => {
    const orphans = context.project.children?.filter(
        child => child.kind === ReflectionKind.Accessor
    ) ?? [];
    for (const orphan of orphans) {
        context.project.removeReflection(orphan);
    }
});

Technical details

  • Root cause: a symbol-identity mismatch during TypeDoc's processing of JavaScript getter/setter pairs causes typedoc-plugin-missing-exports to re-surface the symbols as missing top-level exports. Bare {@link memberName} references in sibling JSDoc are not the trigger — they already resolve correctly to the class member.
  • Scope: the filter is narrow (kind === ReflectionKind.Accessor at the project root only). Callbacks, typedefs, interfaces and everything else typedoc-plugin-missing-exports surfaces (correctly) continues through untouched.
  • Safety: the engine exports no legitimate top-level accessors, so no valid documentation can be removed by this sweep.

Verification

  • TypeDoc build: 0 errors / 9 warnings (unchanged from baseline).
  • "Other" category no longer present on the generated docs/index.html.
  • Class pages (Material, GraphNode, Layer, etc.) still render all their accessors, and bare {@link} references in sibling JSDoc resolve to the correct #anchor on those class pages.
  • Full rendered-HTML audit: 0 broken cross-page links (12,828 scanned), 0 broken anchor links (50,035 scanned).

Public API changes

None. This change only affects the generated API reference documentation.

Remove the ~57 orphan accessor entries that `typedoc-plugin-missing-exports`
was incorrectly hoisting out of their owning classes into the project root.
These showed up on the API reference index page with broken self-links.

The canonical per-class accessor documentation is unaffected; only the
project-root duplicates are swept.

Made-with: Cursor

Copilot AI left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Pull request overview

Updates the repository’s custom TypeDoc plugin to post-process the reflection graph and remove incorrectly hoisted top-level accessor reflections, eliminating noisy/broken “Other” entries on the generated API reference index.

Changes:

  • Add a Converter.EVENT_RESOLVE_END hook to remove project-root ReflectionKind.Accessor reflections.
  • Document why these reflections are removed (broken anchors / duplicates of class-member accessors).

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

@willeastcott willeastcott merged commit 81cea12 into main Apr 21, 2026
8 checks passed
@willeastcott willeastcott deleted the docs/other-category-accessor-sweep branch April 21, 2026 10:29
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

docs Documentation related

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants