docs(v4): link every public export to its documentation page - #868
Merged
Conversation
Code ReviewRisk: Low — No concrete defects were found in the opened diffs; the change is safe to merge aside from the unreviewed files listed below. Adds documentation links to public v4 exports, adds anchors to utility documentation, and introduces a source guard that checks links for subpath exports. It also updates the diagnostics guard to ignore comments before scanning source. I reviewed Notes:
Review usage: 53,546 in (33,028 cached) / 1,231 out tokens — $0.0182 (openrouter/openai/gpt-5.6-luna, thinking: low) Reviewed by @weareikko/code-review v0.9.5 for commit 7d2489e. Previous review runsPrevious run archived 2026-08-26T18:03:15ZCode ReviewRisk: Low — No concrete defects were identified in the reviewed changes; the documentation-only additions and validation scripts are safe to merge aside from the unreviewed files listed below. This change adds documentation links to public v4 exports, expands utility documentation with per-symbol anchors, and adds source checks for missing links and diagnostic guard false positives. I reviewed Notes:
Review usage: 324,464 in (286,243 cached) / 3,526 out tokens — $0.0488 (openrouter/openai/gpt-5.6-luna, thinking: low) Reviewed by @weareikko/code-review v0.9.5 for commit 65ab599. |
v3 puts `@link https://js-toolkit.studiometa.dev/…` at the end of the docblock on each exported symbol. This does the same for v4's 193 public exports, against js-toolkit-v4.studiometa.dev. The link goes on the implementation, never on `src/subpaths/*`: those stubs are generated re-exports with no comment of their own, so an editor follows them through to the implementation anyway. The utils pages gained an `###` per function so the links land on the symbol rather than the section — v4 documents utils as category pages, where v3 had a page each, and a link to `/utils/math.html` would have been a page-level answer to a symbol-level question. The 24 easing functions each get an anchor too, with the curve table linking into them. Every URL was derived from the built HTML and verified against it: 193 links, each resolving to a page that exists with an anchor that exists. `check-doc-links.js` keeps that true for exports added later — it asserts the link exists rather than resolving it, since resolving an anchor means building the site and this runs on every `npm test`. The build already catches a dead link through VitePress' own check. `check-diagnostics.js` now strips comments before its three guards. All three are about emitted code, and testing raw source made prose trip them: `@link .../DIAGNOSTICS.html` matched the `DIAGNOSTICS.` reference test. The guard still catches a real `console.log` — verified both ways. Co-Authored-By: Claude Opus 5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_012ioM9dGKVhexCv4NLUcbA7
titouanmathis
force-pushed
the
feat/v4-doc-links
branch
from
August 26, 2026 18:02
65ab599 to
7d2489e
Compare
Export sizeBundled per export with peer dependencies left external, dynamic imports excluded and the output minified; sizes are gzipped. ✅ No export size changes. Unchanged (399)@studiometa/js-toolkit
@studiometa/js-toolkit-v4
|
Codecov Report✅ All modified and coverable lines are covered by tests. Additional details and impacted files@@ Coverage Diff @@
## main #868 +/- ##
=======================================
Coverage 97.06% 97.06%
=======================================
Files 176 176
Lines 4561 4561
Branches 1330 1330
=======================================
Hits 4427 4427
Misses 122 122
Partials 12 12
Flags with carried forward coverage won't be shown. Click here to find out more. ☔ View full report in Codecov by Harness. 🚀 New features to boost your workflow:
|
v4 mount benchmarksBase and head measured on this runner, alternating over 3 rounds each; every value is the median of the round medians. Running both sides on one machine is what removes cross-machine noise — a cached baseline from another runner would put it back. A move under 25%, or on a benchmark under 5 ms, is not reported as a change: it is inside the measured noise of a shared runner. No benchmark moved beyond the noise floor. Within noise (18)
|
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
1 participant
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.
Follow-up to #867. Based on
feat/v4-docs— the utils pages it edits only exist there. GitHub will retarget this tomainwhen #867 merges.v3 puts
@link https://js-toolkit.studiometa.dev/…at the end of the docblock on each exported symbol. This does the same for v4, againstjs-toolkit-v4.studiometa.dev.Coverage
193 public exports, 193 links.
/** … */expanded to a blockThe 30 without a docblock are the 24 easing functions plus
Base,defaultSchedulerand four storage constants; each got a one-line description alongside the link rather than a bare@link.The link goes on the implementation, never on
src/subpaths/*— those stubs are generated re-exports with no comment of their own, so an editor follows them through to the implementation anyway. Both the barrel import and the subpath import therefore show it.The utils pages gained a
###per functionv4 documents utils as 14 category pages where v3 had a page each, so
clamplived under a## Rangesheading. A link to/utils/math.htmlwould have been a page-level answer to a symbol-level question, so every documented function now has its own anchor —/utils/math.html#clamp.The section prose is kept: the shared example stays at the section level, and each function gets a signature and its own note underneath. The 24 easings each get an anchor too, with the curve table linking into them.
Every link was verified, not assumed
The URLs were derived from the built HTML, not written by hand: for each symbol, a page named after it, else an anchor matching its slug, else an explicit mapping for the grouped pages (the 9 mixins, the storage presets and providers,
read/write, the breakpoint trio).Then re-checked after insertion, reading the
@linktags back out of the source and resolving each againstdist:scripts/check-doc-links.jskeeps that true for exports added later, wired intonpm run test:v4beside the existing guards. It asserts the link exists rather than resolving it — resolving an anchor means building the site, and this runs on every test. VitePress' own dead-link check covers the other half at build time.One guard needed fixing
check-diagnostics.jstests raw source forconsole.,reportError(andDIAGNOSTICS.. My link@link .../DIAGNOSTICS.htmlmatched the third one — a false positive on a comment.All three guards are about emitted code, and a comment is gone by the time the bundle exists, so the script now strips block comments and whole-line
//comments first. This was a latent bug: any prose mentioningDIAGNOSTICS.component.loadFailedwould have tripped it. I verified both directions — it passes now, and it still catches a realconsole.logappended toregistry.ts.Checks
Note for review
The links point at
js-toolkit-v4.studiometa.dev, which is correct while v4 is the prototype. When v4 ships as@studiometa/js-toolkit4.0 and the docs move tojs-toolkit.studiometa.dev, this is a one-line find-and-replace acrosssrc/plus the constant incheck-doc-links.js.🤖 Generated with Claude Code
https://claude.ai/code/session_012ioM9dGKVhexCv4NLUcbA7