Repository navigation
docs(tooling): Enforce JSDoc for public APIs [skip chg] - #12282
Closed
Timothee Guerin (timotheeguerin) wants to merge 4 commits into
Closed
Timothee Guerin (timotheeguerin) wants to merge 4 commits into
Timothee Guerin (timotheeguerin) wants to merge 4 commits into
Conversation
29 of 30 tasks
|
You can try these changes here
|
Timothee Guerin (timotheeguerin)
marked this pull request as ready for review
October 16, 2026 13:44
Timothee Guerin (timotheeguerin)
requested review from
catalinaperalta,
iscai-msft,
Laurent Mazuel (lmazuel) and
Mark Cowlishaw (markcowl)
as code owners
October 16, 2026 13:44
Contributor
There was a problem hiding this comment.
🟡 Changes recommended
Identity collisions and traversal omissions allow new undocumented APIs to bypass the check.
3 open findings
What changed in this PR
Adds a public JavaScript documentation check to prevent new undocumented APIs while existing documentation gaps are addressed.
Changes:
- Checks public entry points and exposed types against an identity-based baseline.
- Integrates enforcement into
check:eng. - Documents exclusions, source mappings, and baseline pruning.
| File | Description |
|---|---|
package.json |
Adds the documentation command and engineering-check integration. |
eng/common/scripts/check-public-jsdoc.ts |
Implements API discovery, documentation traversal, and baseline enforcement. |
eng/common/scripts/check-public-jsdoc.md |
Explains coverage, exceptions, and contributor workflow. |
🧠 Review effort: Balanced
💡 Configure MCP servers for context-aware, tailored reviews. Learn more in the docs.
Comment on lines
+454
to
+458
| const names = [qualifiedDeclarationName(decl, symbol.name)!]; | ||
| for (let node = decl.parent; node && !ts.isSourceFile(node); node = node.parent) { | ||
| const name = qualifiedDeclarationName(node); | ||
| if (name !== undefined) names.unshift(name); | ||
| } |
Comment on lines
+582
to
+589
| if (symbol.flags & ts.SymbolFlags.Module) { | ||
| for (const child of checker.getExportsOfModule(symbol)) visitSymbol(child); | ||
| } else { | ||
| if (symbol.flags & ts.SymbolFlags.Type) visitType(checker.getDeclaredTypeOfSymbol(symbol)); | ||
| if (symbol.flags & ts.SymbolFlags.Value) { | ||
| visitType(checker.getTypeOfSymbolAtLocation(symbol, declarations(symbol)[0])); | ||
| } | ||
| } |
Comment on lines
+685
to
+692
| const decl = declarations(property)[0]; | ||
| if (!decl) continue; | ||
| if (owned(property) && !seenSymbols.has(property)) { | ||
| seenSymbols.add(property); | ||
| record(property); | ||
| } | ||
| context = identity(property); | ||
| visitType(checker.getTypeOfSymbolAtLocation(property, decl)); |
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
New public JavaScript APIs can currently add undocumented surface while documentation backfills are in flight. Add an identity-based no-regression check: fixing an old gap cannot offset a new undocumented member.
pnpm check:public-jsdocchecks all 74 resolved public entry points across 31 publishable packages independently;check:engincludes it.--pruneonly retires existing debt and cannot approve a new gap. The generated baseline is explicit debt, not a permitted count.A later
Box<Metadata>result still requiresMetadatadocumentation even ifBox<string>was checked first. Mapped types expose their selected members, not omitted implementation details.This is source-level summary enforcement, accepting inherited/linked documentation and excluding internal/nonpublic declarations. The four client emitters are excluded; shared
http-clientand allemitter-frameworkcomponents remain included. Existing unavailabletspdroot,protobuf/testing, andhttp-specsroot entries are visible, target-pinned exceptions, invalidated when their source/artifact appears. CSS, JSON and TypeSpec assets have no JavaScript documentation surface.Validation uses the actual command with temporary public-member, inheritance, internal-export, alias/signature-type, mapped-type, augmentation and unresolved-entry changes—not committed build-script fixtures. No package sources or dependencies are changed.
Windows path handling was also validated on real Windows builds with Node 22, 24 and 26.
Part of #12228.