Skip to content

Hide underscore-prefixed APIs from the reference - #2

Merged
Kheartz merged 1 commit into
hogwarts-mp:mainfrom
Kheartz:claude/hide-underscore-apis-docs-a7bfd5
Oct 9, 2026
Merged

Kheartz merged 1 commit into
hogwarts-mp:mainfrom
Kheartz:claude/hide-underscore-apis-docs-a7bfd5

Conversation

@Kheartz

@Kheartz Kheartz commented Oct 9, 2026

Copy link
Copy Markdown
Member

Summary

The Mod publishes its QA and diagnostic hooks in the scripting contract under underscore-prefixed names, and the reference rendered all of them as public API. Contract 1.7.1 has 61 of them, all in the Client API: 15 on Game, 10 on LocalPlayer, 3 on HousePoints, others on Hud, Spells, World, Doors and more, plus the _Beasts global, which gets its own page at /reference/client/variables/beasts/.

This PR adds scripts/public_contract.mjs. The build now copies the downloaded contract and removes every underscore-prefixed declaration from that copy, along with the doc comment above it, before passing the typings to services-cli.

  • Removed declarations become blank lines, so every remaining "Defined in: api.d.ts:N" still matches the published contract.
  • The contract, its integrity-checked cache, and the Mod are not changed. The hooks still exist at runtime and in the publicly downloadable contract. They just aren't documented on the site anymore.
  • services-cli has no option for this (checked 0.8.0 and 0.10.0), so the filter lives here.

Known leftovers (Mod-side text)

  • LocalPlayerStateInfo.isInvulnerable() still mentions _setInvulnerable(seconds) in its description.
  • The LocalPlayerRagdoll interface is still documented, but LocalPlayer._ragdoll was the only way to reach it.

Verification

  • Ran TypeDoc 0.28.20 (the version services-cli 0.8.0 bundles, with the same options) on the current testing contract, with and without the filter. Both runs had 0 errors and 0 warnings. With the filter there are 175 pages instead of 176 (the Beasts page is gone), and the diff contains only removed lines, all from underscore members' sections.
  • Built and served the full site locally: no underscore APIs on Game, LocalPlayer, HousePoints, or the Client API index, and /reference/client/variables/beasts/ returns 404. Public members keep the same line numbers as the live site (for example, HousePoints is at api.d.ts:4146 on both).
  • Edge cases checked: members without semicolons, multi-line union types, arrow-function types, interface bodies, CRLF line endings, doc comments on the same line, and underscore names inside comments or type references (left alone).

Local builds on Windows don't currently work: Node can't spawn pnpm, and services-cli passes backslash paths that TypeDoc rejects. Both problems predate this change. The local check above used a patched throwaway copy of the CLI, so the Linux build in this PR's CI is the first unmodified full build.

The Mod publishes its QA and diagnostic hooks in the scripting contract
under underscore-prefixed names (Game._openMap, HousePoints._probe,
LocalPlayer._ragdoll, the _Beasts global and 57 others). The reference
rendered all of them as public API, including a standalone page for
_Beasts that TypeDoc names "Beasts".

The build now copies the downloaded contract and drops every
underscore-prefixed declaration, together with the doc comment above
it, before handing the typings to services-cli. Removed declarations
are replaced by blank lines so each remaining "Defined in: api.d.ts:N"
still points at the published contract. The contract itself, its
cache, and the Mod are untouched; the hooks remain callable.
@Kheartz
Kheartz merged commit e4739df into hogwarts-mp:main Oct 9, 2026
1 check passed
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.

1 participant