docs: sync package JSDoc with docs content and add verification script - #1770
Merged
dinwwwh merged 4 commits intoAug 3, 2026
Merged
Conversation
Every @orpc/* API mentioned in apps/content/docs now carries JSDoc with an orpc.dev backlink, following one repo-wide template (@remarks with **Warning**/**Note**, pipe-form @see links titled by sidebar label, no @example). Legacy @info/@warning tags, space-form links, {@see} misuses and broken @example fences are normalized away. scripts/verify-docs-jsdoc.ts (pnpm docs:check-jsdoc, wired into CI) extracts docs-mentioned imports, resolves them to declarations via the TypeScript compiler API, and validates JSDoc presence, backlink URLs, and anchors against the content pages. It also caught several docs bugs (wrong import specifiers in next.md, deprecated CORSPlugin imports, a broken redis publisher example) which are fixed here.
|
The latest updates on your projects. Learn more about Vercel for GitHub.
|
More templates
@orpc/ai-sdk
@orpc/arktype
@orpc/bun
@orpc/client
@orpc/cloudflare
@orpc/contract
@orpc/experimental-effect
@orpc/evlog
@orpc/hibernation
@orpc/json-schema
@orpc/nest
@orpc/next
@orpc/openapi
@orpc/opentelemetry
@orpc/pinia-colada
@orpc/pino
@orpc/publisher
@orpc/ratelimit
@orpc/server
@orpc/shared
@orpc/swr
@orpc/tanstack-query
@orpc/trpc
@orpc/valibot
@orpc/zod
commit: |
Codecov Report✅ All modified and coverable lines are covered by tests. 📢 Thoughts on this report? Let us know! |
Contributor
Merging this PR will degrade performance by 10.18%
Warning Please fix the performance issues or acknowledge them on CodSpeed. Performance Changes
Tip Investigate this regression by commenting Comparing 
|
![pullfrog[bot]](https://avatars.githubusercontent.com/in/1768019?s=60&v=4){kind=small}
Contributor
There was a problem hiding this comment.
✅ No new issues found.
Reviewed changes: ~124 source files across all 30+ packages received JSDoc with @see backlinks, alongside a TypeScript-compiler-API-based verification script in CI, docs fixes in 4 pages, and a CONTRIBUTING.md convention section.
- JSDoc sweep — every docs-mentioned symbol now carries a 1-3 sentence summary, optional
@remarksblock, and a pipe-form@see {@link https://orpc.dev/docs/... | Title}tag. Legacy@info/@warningtags are converted repo-wide to@remarkswith**Note**:/**Warning**:, stale anchors are fixed, and broken@examplefences are closed. Even third-party re-exports (getEventMeta,withEventMeta,HibernationAsyncIteratorClass) are documented on their re-export specifiers. - Verification script (
scripts/verify-docs-jsdoc.ts) — extracts imports from docs code fences, resolves declarations through the TS compiler API (includingexport * fromchains and aliases), and enforces that every mentioned symbol has JSDoc with a validorpc.devbacklink whose page exists and whose optional anchor matches a real heading. Reports warnings when the linked page never mentions the symbol (--strictpromotes to error). Passes cleanly: 0 errors, 0 warnings (also clean with--strict). - CI hook —
pnpm docs:check-jsdocadded to thelint_and_typecheckjob. - Docs fixes caught by the script — 3 pages had incorrect imports (
CORSPlugin→CORSHandlerPlugin, next hooks import path errors, publisher Redis variable reference), plus a copy-pasted ratelimit comment fixed. - CONTRIBUTING.md — replaces the old Structure section with a new "JSDoc & Documentation Links" section documenting the convention and template.
DeepSeek Pro (free via Pullfrog for OSS) ｜ 𝕏
Link titles now come from the docs pages themselves: the page's first heading for page-level links, and 'Page Title - Heading' for anchored links. The verify script enforces this (new E6 check) and its heading slugifier now matches VitePress' real algorithm (special characters become dashes instead of being stripped), which also un-broke anchors like #query-mutation-key.
Contributor
There was a problem hiding this comment.
✅ No new issues found.
Reviewed changes — second commit (c6630aa) brings link-title accuracy and a tighter verification baseline:
- Updated
@seelink titles to real page titles — ~150 JSDoc@seelinks across all packages now carry the page's actual first heading as their title, withPage Title - Headingformat when the link targets an anchor. For example| AI SDKbecame| AI SDK Integration - Tool Implementer, and| Ratelimitbecame| Rate Limit Helpers - Adapters. - E6 enforcement in the verification script — the script now validates that
@seelink titles match the real page title (orPage Title - Headingfor anchors), rejecting incorrect or missing titles. Page titles and heading text are extracted from the docs markdown source, and theslugify()function was tightened to match VitePress's@mdit-vue/sharedslugification (control character stripping, smart-quote handling, leading-digit_prefix). - CONTRIBUTING.md — JSDoc convention updated to document the title format rule.
DeepSeek Pro (free via Pullfrog for OSS) ｜ 𝕏
The verify script now scans every packages/*/src file for https://orpc.dev/docs/... URLs anywhere in JSDoc or comments - inline markdown links and member-level docs included, not just @see tags on docs-mentioned symbols - and fails when the page or #anchor does not exist in apps/content. Existence only; title enforcement stays on @see.
Contributor
There was a problem hiding this comment.
Reviewed changes — third commit (afbc47d) extends the verification script to validate orpc.dev links in package source files:
scanSourceLinksfunction — scans everyhttps://orpc.dev/docs/...URL in package.ts/.tsxsources (JSDoc prose, inline markdown, member-level doc comments) and validates page existence and anchor correctness. Only checks existence — title validation (E6) is reserved for@seetags.Issuetype decoupled fromMention—mention: Mentionreplaced withgroup: string,label: string, andnote?: string, so link-scan reports don't need a syntheticMentionobject. All existing per-mention checks (E1–E6, W1, W2) and their output formatting are preserved identically.- Output formatting refactored —
bySpecifier→byGroup, and the summary line now reads... docs-mentioned symbols and N orpc.dev links.
DeepSeek Pro (free via Pullfrog for OSS) ｜ 𝕏
The source-link scan now validates every https://orpc.dev/... URL, not just /docs/ ones: blog, learn-and-contribute, and the homepage resolve against apps/content (index.md maps to the site root, nested index.md to its directory path, trailing slashes ignored).
Contributor
There was a problem hiding this comment.
✅ No new issues found.
Reviewed changes — fourth commit (a1d5e65) extends the verification script to cover the entire content site, not just /docs/:
- Generalized page collection —
collectDocs()now scans all markdown files inapps/content(homepage, blog, etc.) and keys the homepage as''matching its root URL. Onlydocs/pages contribute to@orpc/*import tracking. - Expanded link scanning —
scanSourceLinks()now validates everyhttps://orpc.dev...URL in package sources (previously only/docs/...), with path normalization so root URLs resolve to theindexpage. - Directory skipping —
findFiles()now ignoresnode_modules,.vitepress,public, anddistduring file traversal. - CONTRIBUTING.md updated to document the expanded validation scope.
DeepSeek Pro (free via Pullfrog for OSS) ｜ 𝕏
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.
Every
@orpc/*API mentioned in the docs content now carries JSDoc with a backlink to orpc.dev, and a new verification script keeps the two in sync. The script runs in CI, so docs and JSDoc can no longer drift.JSDoc sweep
@remarkswith**Warning**:/**Note**:, and@see {@link https://orpc.dev/docs/... | Page Title}as the last tag (titles taken from the real page titles, or "Page Title - Heading" for anchored links).os,oc,createORPCClient, everyRPCHandler/RPCLink/OpenAPIHandleradapter,OpenAPIGenerator, all plugins, schema converters, publisher/ratelimit backends, and the previously zero-coverage packages (bun, cloudflare, nest, next, pino, opentelemetry, evlog, arktype, valibot).@info/@warningtags became@remarksnotes, space-form{@link url Title Docs}links became pipe form,{@see}misuses and a stray@returnare fixed, and two broken@examplefences are closed.getEventMeta,withEventMeta,HibernationAsyncIteratorClass) are documented on their re-export specifiers.Verification script
pnpm docs:check-jsdoc(scripts/verify-docs-jsdoc.ts, no new dependencies) extracts everyimport { X } from '@orpc/...'in docs code fences, resolves each identifier to its declaration through the TypeScript compiler API (includingexport * fromchains and aliases), and fails CI when a declaration lacks JSDoc, lacks an orpc.dev backlink, links a nonexistent page, or uses an anchor that matches no heading, or titles a link with anything but the real page title (+ heading for anchors). It also warns when a linked page never mentions the symbol (--strictpromotes this to an error). It also validates everyhttps://orpc.dev/...URL anywhere in package sources (markdown links in prose, member-level docs; docs, blog, and homepage paths all resolve against apps/content) for page and anchor existence. Supports--filter,--listfor incremental work. Added to thelint_and_typecheckjob.Docs bugs the script caught (fixed here)
integrations/next.mdimported four helpers from the wrong specifier (@orpc/next/hooksinstead of@orpc/next/@orpc/client).adapters/fetch-api.mdandopenapi/scalar.mdimported the deprecatedCORSPluginwhile instantiatingCORSHandlerPlugin.helpers/publisher.mdredis example referenced an undefinedredisvariable and carried a copy-pasted ratelimit comment.#using-createsafeclient) now point at real headings.Testing
pnpm docs:check-jsdoc: 0 errors, 0 warnings across 196 docs-mentioned symbols (also clean with--strict).pnpm lint,pnpm type:check, andpnpm --filter @orpc/bun type:checkall pass (cloudflare/nest type-check as part of the recursive run).CONTRIBUTING.md documents the convention in a new "JSDoc & Documentation Links" section.