docs(vue-query): add JSDoc and generate reference docs with TypeDoc - #11378
Draft
sukvvon wants to merge 4 commits into
Draft
docs(vue-query): add JSDoc and generate reference docs with TypeDoc#11378sukvvon wants to merge 4 commits into
sukvvon wants to merge 4 commits into
Conversation
Contributor
|
Important Draft PR not reviewedDraft PRs are not automatically reviewed by default.
To automatically review draft PRs, update your CodeRabbit configuration: reviews:
auto_review:
drafts: trueThanks 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 |
|
View your CI Pipeline Execution ↗ for commit 7e996f0
☁️ Nx Cloud last updated this comment at |
Contributor
🚀 Changeset Version Preview2 package(s) bumped directly, 23 bumped as dependents. 🟨 Minor bumps
🟩 Patch bumps
|
Contributor
size-limit report 📦
|
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.
🎯 Changes
Adds JSDoc across
packages/vue-query/src/(18 of 19 files —index.tsis export-only), then switchesdocs/framework/vue/reference/from 14 hand-written flat files to TypeDoc-generated output (functions/,classes/,type-aliases/,variables/,index.md) — the entry point registered in #11374.docs/config.json'svueframework section is rebuilt to match (14 → 41 entries), followingindex.md's generation order (Classes → Type Aliases → Variables → Functions, alphabetical within each group), same as react/preact/solid.vue-query has no react-query source to port JSDoc from for 4 files with no react equivalent (
useQueryClient.ts,vueQueryPlugin.ts,queryClient.ts,queryCache.ts/mutationCache.ts,utils.ts) — these were written directly from source, cross-checked againstdocs/framework/vue/installation.md/quick-start.mdfor accurate usage. All@examples use Vue 3<script setup>— vue-query supports Vue 2.6+/3.3+ viavue-demi, but the composable API surface is identical either way, and this matches every existing vue-query doc.Reactivity notes baked into the JSDoc, per
docs/framework/vue/reactivity.md:queryKey/enabledtrack reactive dependencies (ref, plain value, or a reactive getter() => ...); other options are read once.queryOptions/infiniteQueryOptions/mutationOptionshave an extra getter-function overload (() => ({...})) beyond react-query's plain-object-only shape — confirmed via__tests__/queryOptions.test-d.ts/mutationOptions.test-d.ts. Documented as the pattern for keepingqueryClient.invalidateQueries/fetchQueryreading currentrefvalues instead of ones captured at options-creation time.What's lost, and how it was handled:
hydration.md's per-option field descriptions (shouldDehydrateMutation,serializeData,shouldRedactErrors,hydrate'sdefaultOptions) don't survive —dehydrate/hydrateare re-exported from@tanstack/query-core, which is excluded from every adapter's TypeDoc entry point (same tradeoff as react/preact/solid). Unlike react (which left this gap unfilled), this PR recovers it: the option descriptions are folded intoguides/ssr.md's existing "Tips, Tricks and Caveats" section as a new## dehydrate/hydrate optionssubsection, rather than resurrecting a flatreference/hydration.mdpage (which would go stale — the framework's convention is generated-only underreference/).useQuery.md's vue-specific caveat onselect("since a Vuesetup()function only runs once per component instance, an inlineselectfunction already has a stable reference") isn't something a mapped-type option object (QueryOptions) can carry per-field JSDoc for — added toqueryOptions.ts'sQueryOptionstype-level JSDoc instead, where it now shows up on every generated options reference page.retry,gcTime,networkMode,select's core behavior, etc.) don't survive, since@tanstack/query-coreis excluded from every adapter's TypeDoc entry point and these fields live on core types — this mirrors the react/preact/solid tradeoff exactly, not a new vue-specific loss.overview.md/reactivity.mdstill pointing at the old flatreference/useQuerypath.All 13 other deleted pages (
infiniteQueryOptions.md,mutationOptions.md,queryOptions.md,useInfiniteQuery.md,useIsFetching.md,useIsMutating.md,useMutation.md,useMutationState.md,usePrefetchInfiniteQuery.md,usePrefetchQuery.md,useQueries.md,useQuery.md,useQueryClient.md) were verified line-by-line against their replacement pages — no other content loss found.✅ Checklist
pnpm run test:pr, or these tests do not apply to this pull request.🚀 Release Impact