fix(repo,shared): backfill inline-object JSDoc on Omit/Pick-resolved types by alexisintech · Pull Request #9052 · clerk/javascript

alexisintech · 2026-06-30T21:42:09Z

Description

Restores JSDoc comments on inline anonymous object literal property reflections that TypeDoc loses when a type is resolved through Omit<…> / Pick<…>. Concretely fixes the empty descriptions on telemetry?.debug? and telemetry?.perEventSampling? rows in react/clerk-provider-props.mdx (and any sibling page that flattens the same inline shape).

Root cause. When TypeScript walks ClerkProviderProps = Omit<IsomorphicClerkOptions, …> & {…}, the inline { debug?, disabled?, perEventSampling? } arm of telemetry gets re-synthesized — and only the leading property's JSDoc survives. The same shape on the un-resolved IsomorphicClerkOptions['telemetry'] carries all three comments correctly. Confirmed with debug logging: the buggy reflection had children with comment === undefined on debug and perEventSampling; the clean reflection elsewhere in the project had all three.

Fix. .typedoc/custom-plugin.mjs: at RendererEvent.BEGIN (after cross-package merging), group TypeLiteral reflections by structural fingerprint (sorted (name, type, optional) tuples of property children); within each group, copy missing comments from the most-commented sibling onto the others. Single-pass mutation on the project model so every render path sees correct data.

Also ships a small JSDoc tidy on BillingNamespace / OrganizationDomainResource (separate commit): add missing @returns annotations and drop stale /nextjs/ segments from doc links.

Verification. Diffed pre-fix vs post-fix .typedoc/docs — exactly one file changed (react/clerk-provider-props.mdx), two lines, just the previously-empty cells filled in. No collateral changes elsewhere. .typedoc vitest suite: 16/16 pass.

Checklist

pnpm test runs as expected.
pnpm build runs as expected.
(If applicable) JSDoc comments have been added or updated for any package exports
(If applicable) Documentation has been updated

Type of change

Summary by CodeRabbit

Documentation
- Improved generated API docs for billing and organization references with clearer @returns text and updated reference links.
- Expanded JSDoc for billing credit-related types and parameters, including additional field documentation (e.g., balances, ledger fields, and request params).
Bug Fixes
- Fixed missing or incomplete property-level documentation for inline object literal types in generated reference pages by restoring backfilled comments during doc generation.

When TypeScript resolves a type through `Omit<…>` / `Pick<…>`, inline anonymous object literal property reflections get re-synthesized and TypeDoc only retains the leading property's JSDoc — the rest come through with `comment === undefined`. The same shape elsewhere in the project (e.g. on the un-resolved type) carries all comments correctly. Group `TypeLiteral` reflections by structural fingerprint (sorted `(name, type, optional)` tuples of property children) at `RendererEvent.BEGIN`; within each group, copy missing comments from the most-commented sibling onto the others. Surfaced concretely as the empty descriptions on `telemetry?.debug?` and `telemetry?.perEventSampling?` in `react/clerk-provider-props.mdx`, while the sibling at `shared/clerk-options.mdx` (rendered via the parallel union-arm path) had all three. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

changeset-bot · 2026-06-30T21:42:14Z

🦋 Changeset detected

Latest commit: 8b9da58

The changes in this PR will be included in the next version bump.

This PR includes changesets to release 0 packages

When changesets are added to this PR, you'll see the packages that this PR includes changesets for and the associated semver types

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

vercel · 2026-06-30T21:42:15Z

The latest updates on your projects. Learn more about Vercel for GitHub.

Project	Deployment	Actions	Updated (UTC)
clerk-js-sandbox	Ready	Preview, Comment	Jun 30, 2026 10:52pm
swingset	Ready	Preview, Comment	Jun 30, 2026 10:52pm

coderabbitai · 2026-06-30T21:42:18Z

No actionable comments were generated in the recent review. 🎉

ℹ️ Recent review info

⚙️ Run configuration

Configuration used: Repository YAML (base), Repository UI (inherited)

Review profile: CHILL

Plan: Pro Plus

Run ID: 7283a20d-66cf-427d-91f7-78a34935a484

📥 Commits

Reviewing files that changed from the base of the PR and between 5e7840d and 8b9da58.

📒 Files selected for processing (1)

.typedoc/custom-plugin.mjs

🚧 Files skipped from review as they are similar to previous changes (1)

.typedoc/custom-plugin.mjs

📝 Walkthrough

Walkthrough

This PR adds a Typedoc post-processing step that backfills missing inline object property comments during rendering, and updates JSDoc text and links in billing and organization domain type files.

Changes

Typedoc inline object comment backfill

Layer / File(s)	Summary
Backfill logic and wiring `.typedoc/custom-plugin.mjs`, `.changeset/fix-typedoc-inline-object-comment-backfill.md`	Adds `typeFingerprint` and `backfillInlineObjectChildComments` to group matching `TypeLiteral` reflections and copy missing child comments during `RendererEvent.BEGIN`; includes the changeset.

Billing and organization domain JSDoc updates

Layer / File(s)	Summary
Billing credit JSDoc updates `packages/shared/src/types/billing.ts`	Revises `@returns` docs for `getCreditBalance` and `getCreditHistory`, and expands JSDoc for `BillingCreditBalanceResource`, `GetCreditBalanceParams`, and `BillingCreditLedgerResource`.
Organization domain doc link updates `packages/shared/src/types/organizationDomain.ts`	Updates `@returns` documentation links from `nextjs` to `reference` paths for `prepareAffiliationVerification` and `updateEnrollmentMode`.

Estimated code review effort

🎯 2 (Simple) | ⏱️ ~15 minutes

Possibly related PRs

clerk/javascript#8853: Related Typedoc plugin work in the same post-processing area for property rendering and reflection handling.
clerk/javascript#8977: Updates JSDoc for the same billing credit APIs and resource types in packages/shared/src/types/billing.ts.

Suggested labels

clerk-js

Suggested reviewers

jacekradko
SarahSoutoul

A rabbit hopped through docs and types,
And backfilled comments into rights and cites. 🐇
Credit ledgers, links made clear,
Inline shapes now speak up here.

🚥 Pre-merge checks | ✅ 5

✅ Passed checks (5 passed)

Check name	Status	Explanation
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Title check	✅ Passed	Clearly describes the main change: backfilling inline-object JSDoc for Omit/Pick-resolved types in the Typedoc pipeline.
Docstring Coverage	✅ Passed	Docstring coverage is 100.00% which is sufficient. The required threshold is 80.00%.
Linked Issues check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check	✅ Passed	Check skipped because no linked issues were found for this pull request.

✨ Finishing Touches

📝 Generate docstrings

Create stacked PR
Commit on current branch

_{Comment @coderabbitai help to get the list of available commands.}

pkg-pr-new · 2026-06-30T21:46:17Z

Open in StackBlitz

@clerk/astro

npm i https://pkg.pr.new/@clerk/astro@9052

@clerk/backend

npm i https://pkg.pr.new/@clerk/backend@9052

@clerk/chrome-extension

npm i https://pkg.pr.new/@clerk/chrome-extension@9052

@clerk/clerk-js

npm i https://pkg.pr.new/@clerk/clerk-js@9052

@clerk/electron

npm i https://pkg.pr.new/@clerk/electron@9052

@clerk/electron-passkeys

npm i https://pkg.pr.new/@clerk/electron-passkeys@9052

@clerk/eslint-plugin

npm i https://pkg.pr.new/@clerk/eslint-plugin@9052

@clerk/expo

npm i https://pkg.pr.new/@clerk/expo@9052

@clerk/expo-passkeys

npm i https://pkg.pr.new/@clerk/expo-passkeys@9052

@clerk/express

npm i https://pkg.pr.new/@clerk/express@9052

@clerk/fastify

npm i https://pkg.pr.new/@clerk/fastify@9052

@clerk/hono

npm i https://pkg.pr.new/@clerk/hono@9052

@clerk/localizations

npm i https://pkg.pr.new/@clerk/localizations@9052

@clerk/nextjs

npm i https://pkg.pr.new/@clerk/nextjs@9052

@clerk/nuxt

npm i https://pkg.pr.new/@clerk/nuxt@9052

@clerk/react

npm i https://pkg.pr.new/@clerk/react@9052

@clerk/react-router

npm i https://pkg.pr.new/@clerk/react-router@9052

@clerk/shared

npm i https://pkg.pr.new/@clerk/shared@9052

@clerk/tanstack-react-start

npm i https://pkg.pr.new/@clerk/tanstack-react-start@9052

@clerk/testing

npm i https://pkg.pr.new/@clerk/testing@9052

@clerk/ui

npm i https://pkg.pr.new/@clerk/ui@9052

@clerk/upgrade

npm i https://pkg.pr.new/@clerk/upgrade@9052

@clerk/vue

npm i https://pkg.pr.new/@clerk/vue@9052

commit: 8b9da58

github-actions · 2026-06-30T22:41:08Z

API Changes Report

Generated by Break Check on 2026-06-30T22:52:54.469Z

Summary

Metric	Count
Packages analyzed	19
Packages with changes	0
🔴 Breaking changes	0
🟡 Non-breaking changes	0
🟢 Additions	0

No API Changes Detected

All packages have stable APIs with no detected changes.

Report generated by Break Check

_{Last ran on 8b9da58.}

coderabbitai

Actionable comments posted: 2

🤖 Prompt for all review comments with AI agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

Inline comments:
In @.typedoc/custom-plugin.mjs:
- Around line 595-599: The backfill logic in custom-plugin.mjs is treating empty
comments as missing, so intentionally empty descriptions can be overwritten.
Update the ReflectionKind.Property loop to only copy from bestByName when
child.comment is truly absent, and avoid relying on comment.summary.length as
the missing check; keep any existing empty comment created earlier by
`@generateWithEmptyComment` intact.
- Around line 529-544: The fingerprint logic in `typeFingerprint` is too shallow
for `reference` and `reflection` types, causing collisions between distinct
generic instantiations and inline shapes. Update the `reference` case to
incorporate `t.typeArguments` into the fingerprint, and expand the `reflection`
case to include each child property’s nested type fingerprint in addition to its
name and optional flag. Keep the existing `union` and `intersection` sorting
behavior, and make sure the updated fingerprint remains deterministic for
`ReflectionKind.Property` children.

🪄 Autofix (Beta)

Fix all unresolved CodeRabbit comments on this PR:

Push a commit to this branch (recommended)
Create a new PR with the fixes

ℹ️ Review info

⚙️ Run configuration

Configuration used: Repository YAML (base), Repository UI (inherited)

Review profile: CHILL

Plan: Pro Plus

Run ID: 2b2e5a7f-3e13-48a8-8bec-ff7cb43e1584

📥 Commits

Reviewing files that changed from the base of the PR and between f42aad9 and 4a865b3.

📒 Files selected for processing (4)

.changeset/fix-typedoc-inline-object-comment-backfill.md
.typedoc/custom-plugin.mjs
packages/shared/src/types/billing.ts
packages/shared/src/types/organizationDomain.ts

Tighten the backfill guard so `@generateWithEmptyComment` survivors keep their empty descriptions instead of being overwritten with sibling JSDoc. Treat any `.comment` object as user intent — only fill children with no comment at all, and only from sources whose summary is non-empty. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

… shapes Reference fingerprints now include type arguments and reflection fingerprints recurse into each property's type, so `Foo<string>` vs `Foo<number>` and `{ x: string }` vs `{ x: number }` no longer collide. Threads a shared `Set<number>` of visited reflection ids through the recursion to guard against cycles. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

alexisintech and others added 2 commits June 30, 2026 14:31

update typedocs for billing and organizationdomain

baa7de8

vercel Bot deployed to Preview – clerk-js-sandbox June 30, 2026 21:42 View deployment

remove custom plugin updates

2e5b7dd

vercel Bot deployed to Preview – clerk-js-sandbox June 30, 2026 21:44 View deployment

vercel Bot deployed to Preview – swingset June 30, 2026 21:45 View deployment

fix formatting

1d04b80

vercel Bot deployed to Preview – clerk-js-sandbox June 30, 2026 21:59 View deployment

vercel Bot deployed to Preview – swingset June 30, 2026 22:00 View deployment

alexisintech requested review from SarahSoutoul and jacekradko June 30, 2026 22:02

small copy update

4a865b3

alexisintech force-pushed the aa/fix-typedocs branch from fa8faaa to 4a865b3 Compare June 30, 2026 22:08

vercel Bot deployed to Preview – clerk-js-sandbox June 30, 2026 22:08 View deployment

vercel Bot deployed to Preview – swingset June 30, 2026 22:09 View deployment

alexisintech marked this pull request as ready for review June 30, 2026 22:35

coderabbitai Bot reviewed Jun 30, 2026

View reviewed changes

Comment thread .typedoc/custom-plugin.mjs Outdated

Comment thread .typedoc/custom-plugin.mjs Outdated

vercel Bot deployed to Preview – clerk-js-sandbox June 30, 2026 22:49 View deployment

vercel Bot deployed to Preview – clerk-js-sandbox June 30, 2026 22:50 View deployment

vercel Bot deployed to Preview – swingset June 30, 2026 22:52 View deployment

jacekradko approved these changes Jun 30, 2026

View reviewed changes

alexisintech merged commit 2bc5e36 into main Jun 30, 2026
53 checks passed

alexisintech deleted the aa/fix-typedocs branch June 30, 2026 22:56

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Uh oh!

fix(repo,shared): backfill inline-object JSDoc on Omit/Pick-resolved types#9052

fix(repo,shared): backfill inline-object JSDoc on Omit/Pick-resolved types#9052
alexisintech merged 7 commits into
mainfrom
aa/fix-typedocs

alexisintech commented Jun 30, 2026 •

edited by coderabbitai Bot

Loading

Uh oh!

changeset-bot Bot commented Jun 30, 2026 •

edited

Loading

Uh oh!

vercel Bot commented Jun 30, 2026 •

edited

Loading

Uh oh!

coderabbitai Bot commented Jun 30, 2026 •

edited

Loading

Walkthrough

Changes

Estimated code review effort

Possibly related PRs

Suggested labels

Suggested reviewers

Uh oh!

pkg-pr-new Bot commented Jun 30, 2026 •

edited

Loading

Uh oh!

github-actions Bot commented Jun 30, 2026 •

edited

Loading

Uh oh!

coderabbitai Bot left a comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

Uh oh!

Conversation

alexisintech commented Jun 30, 2026 • edited by coderabbitai Bot Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Description

Checklist

Type of change

Summary by CodeRabbit

Uh oh!

changeset-bot Bot commented Jun 30, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

🦋 Changeset detected

Uh oh!

vercel Bot commented Jun 30, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

coderabbitai Bot commented Jun 30, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Walkthrough

Changes

Estimated code review effort

Possibly related PRs

Suggested labels

Suggested reviewers

Uh oh!

pkg-pr-new Bot commented Jun 30, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

github-actions Bot commented Jun 30, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

API Changes Report

Summary

No API Changes Detected

Uh oh!

coderabbitai Bot left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

alexisintech commented Jun 30, 2026 •

edited by coderabbitai Bot

Loading

changeset-bot Bot commented Jun 30, 2026 •

edited

Loading

vercel Bot commented Jun 30, 2026 •

edited

Loading

coderabbitai Bot commented Jun 30, 2026 •

edited

Loading

pkg-pr-new Bot commented Jun 30, 2026 •

edited

Loading

github-actions Bot commented Jun 30, 2026 •

edited

Loading