fix(docs): regenerate the API pages from JSDoc and gate the drift in CI - #452
Merged
Conversation
…llets or doubled periods replaceDescription escaped apostrophes for every caller, but only the :nested array wraps them in a single-quoted JS string; a double-quoted attribute leaked the backslash into the page. @description was also read with compact spacing, which collapsed its bullet lists into one line, and a nested return description already ending in a period got a second one.
… returns in the generator's shape useList and useSet documented their return shape only in the committed .md, in a layout the generator cannot produce; regenerating would have dropped every action. Both now declare the generic, the optional initial state and each returned member the way useCounter does.
verifySkill.ts compares the skill to the .md pages and nothing compared the pages to their source, so 21 of 55 drifted while CI stayed green. This commit alone is red by design; the next one regenerates the pages.
…tact Preserving the parser's spacing kept the bullet lists but also baked the source's editor wrapping into every page. Blank lines and list items are structure; a line break inside a paragraph is not.
27 pages had drifted: some were left behind after a JSDoc change, the rest carried the escaping, spacing and rest-parameter defects fixed earlier in this branch.
The signature is mergeRefs(...refs) but the JSDoc typed it as a plain array, so the generated page dropped the spread.
🦋 Changeset detectedLatest commit: 5ddd3ea The changes in this PR will be included in the next version bump. This PR includes changesets to release 1 package
Not sure what this means? Click here to learn what changesets are. Click here if you're a maintainer who wants to add another changeset to this PR |
Codecov Report✅ All modified and coverable lines are covered by tests. Additional details and impacted files@@ Coverage Diff @@
## main #452 +/- ##
=========================================
Coverage 100.00% 100.00%
=========================================
Files 58 58
Lines 1664 1664
Branches 500 500
=========================================
Hits 1664 1664 🚀 New features to boost your workflow:
|
Contributor
|
Size Change: +651 B (+0.67%) Total Size: 97.9 kB 📦 View Changed
ℹ️ View Unchanged
|
… import The English useList page took its example from the JSDoc in this branch, replacing a TodoList component the Korean page still mirrored. Two independent reviews also found useSet's Korean snippet missing the import line the English has.
The description check matched the parameter name as [^ -]*, which cannot span the space in a default like [initialState=new Set()] and reported the description as missing. The name now matches either a bracketed form or a bare one; a @PARAM without a description still fails.
…ejoin wrapped bullet lines Review findings on this branch. A double quote in a nested return description survived into the double-quoted :nested attribute and made the Vue formatter throw — dormant only because no current JSDoc contains one. A bullet's first continuation line was left unwrapped while later ones joined, baking the editor's wrapping into two pages. ko/useInterval also gains the required flag the regenerated English page states for options.delay.
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.
Problem
27 of the 55 English API pages had drifted from the JSDoc they are generated from.
verifySkill.tschecks the skill against those pages, but nothing checked the pages against their source, so the skill'sreferences/inherited every stale page while CI stayed green.Regenerating blindly would have made things worse. The drift was three things at once:
\'inside double-quoted attributes,@descriptionbullet lists flattened into one line, doubled periods, rest parameters rendered without the spread.useIntersectionObservertypedoptions.rootasboolean;useListanduseSetdescribed their returns only in the hand-written.md, in a shape the generator cannot produce;mergePropsandmergeRefsdid not mark their rest parameter.useBodyScrollLock's hoisted single-lock example.Approach
Fix the generator, fix the JSDoc, add the gate, then regenerate — in that order so nothing regresses.
.scripts/verifyDocs.tsrenders every public export from its JSDoc and requires the committed page to match byte for byte. The gate commit is red on its own; the regeneration commit turns it green.useListanduseSetnow render their returns as a:nestedarray like the other pages.The CI JSDoc structure check also needed one change: it rejected
[initialState=new Set()]because the name pattern could not span a space.Testing
renderEnglishDoc()was extracted so the generator is testable without the filesystem;.scripts/commands/generateDocs/index.spec.tsis new, each test written failing first.All green:
yarn test,yarn test:docs,yarn test:skill, 521 unit tests at 100% coverage.The 10 Korean pages that changed were reviewed by two independent
translation-reviewerpasses. Findings within this PR's scope are applied. Pre-existing issues they flagged are left alone:함수에요→함수예요in 6 files, inconsistent copula afternavigator.userAgent, and theuseThrottlesummary dropping "React hook".