Repository navigation
fix(docs): stop recording source line numbers in generated API docs - #1805
Conversation
✅ Single Commit Policy - COMPLIANTStatus: Policy requirements met • 1 commit • Valid format • Ready for merge 📊 View validation details📝 Commit Details
✅ Validation Results
🤖 Automated validation by NeuroLink Single Commit Enforcement |
|
Navigate logical layers of code changes, visualize relationships, and explore their blast radius. No actionable comments were generated in the recent review. 🎉 📝 WalkthroughWalkthroughThe CI workflow comment now states that ChangesGenerated API docs drift check
Priority: ⬇️ Low Estimated code review effort: 1 (Trivial) | ~2 minutes Suggested reviewers: Merge Risk: ⚪ Minimal · up to The change documents why generated API pages omit source links. That trade-off is intentional, and no actionable merge risk is evident from the supplied context. Architecture SummaryArchitecture risk: 🔵 Low · up to The changed surface does not map to a changed system, dependency edge, entrypoint, or external dependency. Changed systems: None identified. Architecture concerns Review detailsBefore / after behavior
🚥 Pre-merge checks | ✅ 5✅ Passed checks (5 passed)
✨ Finishing Touches🧪 Generate unit tests (beta)
Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out. Comment |
Documentation Validation Results🚀 Documentation validation passed!
📦 Build artifact uploaded successfully. Ready for deployment preview. Commit: |
Every docs/api page ended with "Defined in: file.ts:LINE", so a PR that added lines near the top of a large type file rewrote every later page. Three comment-only lines added to src/lib/types/providers.ts changed 143 generated pages without touching any API. Two open PRs that edit the same type file then conflicted on all of those pages, whatever they changed. On 2026-09-26 that was nearly every conflict in the open queue: #1800 hit 110 conflicting docs/api pages and no code conflict. It also inflated diffs: #1800 is 162 files for about 12 real changes. typedoc.json now sets disableSources. The same three-line probe changes 0 pages, so docs/api changes only when a documented API changes, and the CI drift gate keeps working. The regeneration here removes the "Defined in" line from all 3,662 pages and changes nothing else (37,832 deleted lines, one added). Trade-off: the generated pages lose their link to the source line. docs/api is excluded from the docs site (docusaurus docs.exclude "**/api/**"), so this only affects reading the markdown on GitHub.
851713b to
22c0cf4
Compare
Tara-ag
left a comment
Tara-ag
left a comment
There was a problem hiding this comment.
APPROVE — clean, well-justified docs churn reduction: typedoc.json sets disableSources: true and the docs are regenerated to match, so docs/api only changes when a documented API actually changes.
APPROVE ✅Clean, well-justified docs-churn reduction. Findings
What was checked — all clean
Review stateFormal approving review submitted separately on this PR, matching the verdict. Checked: diff, existing comments (3 bot comments — no author replies that would require a response), full |
|
🎉 This PR is included in version 12.28.3 🎉 The release is available on: Your semantic-release bot 📦🚀 |
2 participants
What
typedoc.jsongains one line:"disableSources": true. The generateddocs/apipages stop ending inDefined in: file.ts:LINE. The regeneration here only removes that line from every page: 3,674 files, 37,881 lines deleted, 5 added (the setting plus a CI comment).To check the diff is mechanical, run
git show --stat HEAD: the only non-docs/apifiles aretypedoc.jsonand a comment in.github/workflows/ci.yml.Why
A source line number on every page means that adding lines near the top of a large type file rewrites every later page. Two open PRs editing the same type file then conflict on all of those pages, whatever they actually changed.
src/lib/types/providers.tsOn 2026-09-26, most of the conflicting PRs in the open queue conflicted only on generated
docs/apipages. For example, #1800 conflicts withreleaseon 110 of them and on no code. The line numbers also bloat diffs: #1800 is 162 files for about 12 real changes. That's probably why the review bot twice exited without posting a review there, though I haven't confirmed that.This is the
docs/apicounterpart of #1794, which did the same fordocs-site/static/search-index.json.Checks
docs:api+ prettier +git status --porcelain docs/api) is clean on this commit.docs-sitebuild:search-index.jsonis unchanged (docs/apiis excluded from the site and the index).format:checkpasses.Trade-off
Generated pages lose their link to the source line.
docs/apiis excluded from the docs site (docusaurus.config.tsdocs.exclude: ["**/api/**"]), so this only affects reading the markdown on GitHub.Summary by CodeRabbit