Skip to content

docs: replace opaque any/* types with real types in API reference#8811

Merged
willeastcott merged 1 commit into
mainfrom
docs/fix-opaque-any-types
May 30, 2026
Merged

docs: replace opaque any/* types with real types in API reference#8811
willeastcott merged 1 commit into
mainfrom
docs/fix-opaque-any-types

Conversation

@willeastcott
Copy link
Copy Markdown
Contributor

@willeastcott willeastcott commented May 30, 2026

Description

Two public, reference-visible members documented their JSDoc types as the opaque */any, which renders as a meaningless any in the generated TypeDoc API reference. This replaces them with accurate types:

  • RenderTarget.getColorBuffer(index)index is an array index, typed {*}{number}.
  • InputConsumer.update() — the base method discards the frame and returns nothing, so the bogus @returns {any} is dropped (per the engine convention of omitting @returns when nothing is returned). The InputController subclass override already documents its {Pose} return.

After the change the generated declarations read getColorBuffer(index: number): Texture, InputConsumer.update(...): void, and InputController.update(...): Pose; the rendered RenderTarget page drops from 2 → 0 any tokens.

Scope note for reviewers

This is a deliberately small, surgical change. A wider audit of @param {*}/{any} usage (~100 hits across 37 files) found that the large majority sit on @private/@ignore members that are excluded from the reference (excludePrivate defaults to true), or are legitimately dynamic public APIs (EventHandler event args, Http response payloads, Asset.resource, uniform values) where any is the correct type. These were the only public, reference-visible members whose type was genuinely recoverable.

Verification

  • npm run lint
  • npm run build:types
  • npm run test:types
  • npm run docs — 0 errors ✅

Checklist

  • I have read the contributing guidelines
  • My code follows the project's coding standards
  • This PR focuses on a single change

🤖 Generated with Claude Code

Copy link
Copy Markdown
Contributor

Copilot AI left a comment

Choose a reason for hiding this comment

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

Pull request overview

This PR improves the generated public API reference by replacing two opaque JSDoc types (* / any) with concrete, recoverable types so TypeDoc and the generated .d.ts don’t expose meaningless any in these APIs.

Changes:

  • Updated RenderTarget.getColorBuffer(index) JSDoc to type index as {number} instead of {*}.
  • Updated InputConsumer.update() JSDoc return type from {any} to {Pose|undefined} to match the controller pose returned by InputController.update() while allowing the base implementation to discard frames.

Reviewed changes

Copilot reviewed 2 out of 2 changed files in this pull request and generated 1 comment.

File Description
src/platform/graphics/render-target.js Refines getColorBuffer parameter type for clearer public API docs / typings.
src/extras/input/input.js Refines InputConsumer.update return type to avoid any in public docs / typings.

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

Comment thread src/extras/input/input.js Outdated
Two public, reference-visible members documented their JSDoc types as the opaque `*`/`any`, which renders as a meaningless `any` in the generated TypeDoc API reference:

- `RenderTarget.getColorBuffer(index)` - `index` is an array index, typed `{*}` -> `{number}`.
- `InputConsumer.update()` - the base method discards the frame and returns nothing, so the bogus `@returns {any}` is dropped (per the engine convention of omitting `@returns` when nothing is returned); the `InputController` subclass override already documents its `{Pose}` return.

Both compile cleanly (build:types/test:types); the generated declarations now read `getColorBuffer(index: number): Texture` and `InputConsumer.update(...): void` / `InputController.update(...): Pose`.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
@willeastcott willeastcott force-pushed the docs/fix-opaque-any-types branch from d0d25bb to dfcbc5b Compare May 30, 2026 14:34
@willeastcott willeastcott merged commit 08c7aab into main May 30, 2026
8 checks passed
@willeastcott willeastcott deleted the docs/fix-opaque-any-types branch May 30, 2026 14:36
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants