docs(repo): Add typedoc comments; generate typedoc output for /objects docs#8276
docs(repo): Add typedoc comments; generate typedoc output for /objects docs#8276alexisintech wants to merge 93 commits into
Conversation
🦋 Changeset detectedLatest commit: 8172b62 The changes in this PR will be included in the next version bump. This PR includes changesets to release 20 packages
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 |
|
The latest updates on your projects. Learn more about Vercel for GitHub.
|
alexisintech
changed the title
This reverts commit 9100976.
alexisintech
changed the title
alexisintech
changed the title
…ct>-methods folder
|
unsafeMetadata section added successfully: 
|
@clerk/astro
@clerk/backend
@clerk/chrome-extension
@clerk/clerk-js
@clerk/dev-cli
@clerk/expo
@clerk/expo-passkeys
@clerk/express
@clerk/fastify
@clerk/hono
@clerk/localizations
@clerk/nextjs
@clerk/nuxt
@clerk/react
@clerk/react-router
@clerk/shared
@clerk/tanstack-react-start
@clerk/testing
@clerk/ui
@clerk/upgrade
@clerk/vue
commit: |
Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
…orts Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
|
Pushed some changes directly in 9be16f7.
|
Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
…8637) Co-authored-by: Claude Opus 4.7 (1M context) <noreply@anthropic.com> Co-authored-by: Michael Novotny <manovotny@gmail.com>
Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
Register a self-documenting modifier tag and strip it post-resolve so it's indistinguishable from /** */ at render time. Migrate 102 empty doc-comments across packages/shared/src/types/ to use the new tag. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
API Changes Report
Summary
@clerk/sharedCurrent version: 4.14.0 Subpath
|
|
Note Reviews pausedIt looks like this branch is under active development. To avoid overwhelming you with review comments due to an influx of new commits, CodeRabbit has automatically paused this review. You can configure this behavior by changing the Use the following commands to manage reviews:
Use the checkboxes below for quick actions:
No actionable comments were generated in the recent review. 🎉 ℹ️ Recent review info⚙️ Run configurationConfiguration used: Repository YAML (base), Organization UI (inherited) Review profile: CHILL Plan: Pro Run ID: 📒 Files selected for processing (1)
🚧 Files skipped from review as they are similar to previous changes (1)
📝 WalkthroughWalkthroughAdds a TypeDoc generation pipeline and supporting utilities, plus broad JSDoc and a few type-export surface changes. New TypeDoc artifacts: plugins (custom-plugin, extract-methods), theme and router overrides, markdown helpers, slug/reference configs, and utilities (comment-utils, type-utils, standalone-page-tag). The extract plugin emits properties.mdx and methods/*.mdx for configured reference-object pages. Tests and frozen MDX snapshots were added; many package-level type files received expanded JSDoc and a small number of observable export changes (e.g., ClerkOptionsNavigation, WithOptionalOrgType, TelemetryCollector.recordLog, explicit RemoveUserPasswordParams shape). Estimated code review effort🎯 4 (Complex) | ⏱️ ~60 minutes |
![coderabbitai[bot]](https://avatars.githubusercontent.com/in/347564?s=60&v=4){kind=small}
There was a problem hiding this comment.
Actionable comments posted: 8
🧹 Nitpick comments (4)
packages/backend/src/api/endpoints/SessionApi.ts (1)
86-86: ⚡ Quick winAdd explicit return type to
SessionAPI.getToken
packages/backend/src/api/endpoints/SessionApi.tsline 86 currently relies on inference forpublic async getToken(...). Adding: Promise<Token>would improve signature clarity (the resolved type is already effectivelyPromise<Tokenviareturn this.request<Token>(...)).🤖 Prompt for 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. In `@packages/backend/src/api/endpoints/SessionApi.ts` at line 86, Update the async method signature for SessionApi.getToken to explicitly declare its return type as Promise<Token> (i.e., change `public async getToken(sessionId: string, template?: string, expiresInSeconds?: number)` to include `: Promise<Token>`), and ensure the Token type is imported or available in the module so the `return this.request<Token>(...)` remains type-consistent..typedoc/slug.mjs (2)
28-35: ⚡ Quick winAdd
@returnsJSDoc tag for completeness.The function includes
@paramdocumentation but is missing the@returnstag. As per coding guidelines, public API functions should be documented with@param,@returns,@throws, and@exampletags.📝 Suggested JSDoc enhancement
/** * Splits acronyms by also inserting a dash between adjacent uppercase letters when the second one is followed by a lowercase: `OKXWallet` → `okx-wallet`. Used for page URLs. * * `@param` {string} str + * `@returns` {string} The kebab-cased slug suitable for URLs. */ export function toUrlSlug(str) {🤖 Prompt for 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. In @.typedoc/slug.mjs around lines 28 - 35, The toUrlSlug function is missing a JSDoc `@returns` tag; update the JSDoc block above export function to include a `@returns` description indicating it returns a lowercased URL-friendly slug string (e.g., "returns {string} The input converted to a URL slug"), and keep the existing `@param` line and any other tags required by the public API docs (add `@throws/`@example only if applicable).
16-26: ⚡ Quick winAdd
@returnsJSDoc tag for completeness.The function includes
@paramdocumentation but is missing the@returnstag. As per coding guidelines, public API functions should be documented with@param,@returns,@throws, and@exampletags.📝 Suggested JSDoc enhancement
/** * Inserts a dash before every uppercase that immediately follows a lowercase or digit, then lowercases. Treats runs of uppercase letters (acronyms) as a single token: `OKXWallet` → `okxwallet`. Used for `methods/<slug>.mdx` filenames. * * `@param` {string} name + * `@returns` {string} The kebab-cased slug suitable for filenames. */ export function toFileSlug(name) {🤖 Prompt for 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. In @.typedoc/slug.mjs around lines 16 - 26, The JSDoc for toFileSlug is missing a `@returns` tag (and per guidelines also should include `@throws` and `@example` for public APIs); update the comment above export function to add a `@returns` describing that it returns a string (e.g., "The slugified filename string"), optionally add a `@throws` line if the function can error (or explicitly state it does not throw) and a brief `@example` showing usage of toFileSlug('OKXWallet') -> 'okxwallet'..typedoc/custom-theme.mjs (1)
1763-1774: ⚡ Quick winAdd
@returnsJSDoc tag to the exported function.The exported
isCallableInterfacePropertyfunction has@paramdocumentation but is missing a@returnstag. While .mjs files don't require explicit return type annotations (per the TypeScript-specific guidelines), adding a@returnsJSDoc tag for exported public APIs improves documentation clarity—especially important for a documentation-generation tooling file.📚 Suggested improvement
/** * `@param` {import('typedoc').DeclarationReflection} prop * `@param` {import('typedoc-plugin-markdown').MarkdownThemeContext['helpers']} helpers + * `@returns` {boolean} `true` if the property's type is callable (function type, union/intersection of callables, or reference to a callable type alias); `false` otherwise. */ function isCallableInterfaceProperty(prop, helpers) {🤖 Prompt for 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. In @.typedoc/custom-theme.mjs around lines 1763 - 1774, The exported function isCallableInterfaceProperty lacks a `@returns` JSDoc tag; add a `@returns` line to its JSDoc block describing that it returns a boolean (e.g., "`@returns` {boolean} whether the given DeclarationReflection represents a callable interface property") so the public API docs include the return type and description.
🤖 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/__tests__/__snapshots__/clerk-properties.mdx:
- Line 14: The proxyUrl property description contains a sentence fragment;
update the text for `proxyUrl` so the fragment “Can be either a relative path
(...) or a full URL (...)” is rewritten as a full sentence (for example, start
with “It can be either…”), ensuring the description reads as two complete
sentences and preserves the examples and required-note wording.
In @.typedoc/__tests__/__snapshots__/user-resource-properties.mdx:
- Line 33: Update the generated description for the `unsafeMetadata` entry so
the compound adjective is hyphenated: change the phrase in the sentence that
references the `SignUp` object from "once the sign up is complete" to "once the
sign-up is complete". Locate the snapshot text for `unsafeMetadata` (the line
that mentions the `SignUp` object) and replace the unhyphenated "sign up" with
"sign-up" so the generated docs use the correct compound form.
In @.typedoc/__tests__/extract-methods.test.ts:
- Line 8: The comment header is inconsistent with the actual DOCS_DIR used by
the test; update the comment on line 8 to match the real DOCS_DIR constant used
in the test (referenced as DOCS_DIR in the file) so it correctly instructs to
run `pnpm typedoc:generate` and points to the same output directory the test
reads from (i.e., change “.typedoc/docs/” to whatever DOCS_DIR equals, or change
DOCS_DIR to match the comment).
In @.typedoc/comment-utils.mjs:
- Around line 31-50: stripTodoFromDisplayParts only checks p.kind === 'text' so
TODOs inside non-text display parts are not detected/removed; update
stripTodoFromDisplayParts to treat non-text parts as text for matching by
building a running string/offset map (or coerce each part to text via its text
property if present) and when TODO_WORD matches anywhere (regardless of
part.kind) truncate the output at that match: push any partial text before the
match as a final text part and stop processing further parts. Ensure you
reference the TODO_WORD and preserve other display-part objects unchanged up to
the truncation point in stripTodoFromDisplayParts so behavior matches
commentContainsTodo.
In
`@packages/expo/src/local-credentials/useLocalCredentials/useLocalCredentials.ts`:
- Around line 198-199: Update the public JSDoc comment that currently reads
"Indicates whether the stored credentials belong to the signed in uer." to
correct the typo by changing "uer" to "user" so the sentence reads "Indicates
whether the stored credentials belong to the signed in user."; locate the JSDoc
containing that exact phrase in useLocalCredentials.ts (the public API comment
above the related exported symbol) and make the single-word correction so
generated docs are accurate.
In `@packages/shared/src/types/client.ts`:
- Around line 27-33: The JSDoc says signUp/signIn can be null but the fields are
currently non-nullable; update the types to match the docs by changing the
signUp and signIn field types to be nullable (SignUpResource | null and
SignInResource | null) in the client type definition (fields signUp and signIn)
or alternatively update the JSDoc to remove “or `null`” if you intend them to be
non-nullable—pick one approach and keep JSDoc and the declared types for signUp
and signIn consistent.
In `@packages/shared/src/types/multiDomain.ts`:
- Around line 63-75: The type DomainOrProxyUrl currently allows both proxyUrl
and domain to be set despite the JSDoc and runtime behavior in buildScriptHost
which prefers proxyUrl over domain; update the public contract by encoding
mutual exclusivity: replace the single optional-object definition with a union
that enforces either { proxyUrl?: string | ((url: URL) => string); domain?:
never } or { domain?: string | ((url: URL) => string); proxyUrl?: never } and
also allow an empty case if we want neither set; update the JSDoc to match this
XOR semantics and reference proxyUrl/domain and buildScriptHost in the comment
so callers know precedence.
In `@packages/shared/src/types/telemetry.ts`:
- Around line 64-71: Update the duplicated JSDoc for the telemetry properties so
each describes its distinct purpose: change the comment for isEnabled to state
that when true telemetry collection/sending is enabled (otherwise disabled), and
change the comment for isDebug to state that when true telemetry is run in debug
mode (logs to console, includes verbose/debug details, and does not send events
to Clerk). Ensure you update the JSDoc blocks immediately above the isEnabled
and isDebug property declarations to reflect these distinct behaviors.
---
Nitpick comments:
In @.typedoc/custom-theme.mjs:
- Around line 1763-1774: The exported function isCallableInterfaceProperty lacks
a `@returns` JSDoc tag; add a `@returns` line to its JSDoc block describing that it
returns a boolean (e.g., "`@returns` {boolean} whether the given
DeclarationReflection represents a callable interface property") so the public
API docs include the return type and description.
In @.typedoc/slug.mjs:
- Around line 28-35: The toUrlSlug function is missing a JSDoc `@returns` tag;
update the JSDoc block above export function to include a `@returns` description
indicating it returns a lowercased URL-friendly slug string (e.g., "returns
{string} The input converted to a URL slug"), and keep the existing `@param` line
and any other tags required by the public API docs (add `@throws/`@example only if
applicable).
- Around line 16-26: The JSDoc for toFileSlug is missing a `@returns` tag (and per
guidelines also should include `@throws` and `@example` for public APIs); update the
comment above export function to add a `@returns` describing that it returns a
string (e.g., "The slugified filename string"), optionally add a `@throws` line if
the function can error (or explicitly state it does not throw) and a brief
`@example` showing usage of toFileSlug('OKXWallet') -> 'okxwallet'.
In `@packages/backend/src/api/endpoints/SessionApi.ts`:
- Line 86: Update the async method signature for SessionApi.getToken to
explicitly declare its return type as Promise<Token> (i.e., change `public async
getToken(sessionId: string, template?: string, expiresInSeconds?: number)` to
include `: Promise<Token>`), and ensure the Token type is imported or available
in the module so the `return this.request<Token>(...)` remains type-consistent.
🪄 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), Organization UI (inherited)
Review profile: CHILL
Plan: Pro
Run ID: 41c47e90-ab01-4064-a1d8-ed4c96b3161a
📒 Files selected for processing (87)
.changeset/typedoc-objects-jsdoc.md.prettierignore.typedoc/__tests__/__snapshots__/api-key-resource-methods-create.mdx.typedoc/__tests__/__snapshots__/clerk-methods-handle-email-link-verification.mdx.typedoc/__tests__/__snapshots__/clerk-methods-handle-redirect-callback.mdx.typedoc/__tests__/__snapshots__/clerk-methods-join-waitlist.mdx.typedoc/__tests__/__snapshots__/clerk-methods-sign-out.mdx.typedoc/__tests__/__snapshots__/clerk-properties.mdx.typedoc/__tests__/__snapshots__/clerk.mdx.typedoc/__tests__/__snapshots__/session-resource-methods-check-authorization.mdx.typedoc/__tests__/__snapshots__/sign-in-future-resource-methods-email-code-send-code.mdx.typedoc/__tests__/__snapshots__/sign-in-future-resource-methods-email-link.mdx.typedoc/__tests__/__snapshots__/user-resource-properties.mdx.typedoc/__tests__/extract-methods.test.ts.typedoc/__tests__/file-structure.test.ts.typedoc/comment-utils.mjs.typedoc/custom-plugin.mjs.typedoc/custom-router.mjs.typedoc/custom-theme.mjs.typedoc/extract-methods.mjs.typedoc/markdown-helpers.mjs.typedoc/reference-objects.mjs.typedoc/slug.mjs.typedoc/standalone-page-tag.mjs.typedoc/type-utils.mjspackages/backend/src/api/endpoints/ActorTokenApi.tspackages/backend/src/api/endpoints/SessionApi.tspackages/backend/src/api/resources/APIKey.tspackages/backend/src/tokens/authObjects.tspackages/backend/src/tokens/authenticateContext.tspackages/clerk-js/src/core/modules/apiKeys/index.tspackages/clerk-js/src/core/modules/debug/index.tspackages/clerk-js/src/core/resources/Client.tspackages/expo/src/google-one-tap/types.tspackages/expo/src/local-credentials/useLocalCredentials/useLocalCredentials.tspackages/express/src/getAuth.tspackages/nextjs/src/app-router/server/currentUser.tspackages/nextjs/src/server/createGetAuth.tspackages/react/src/components/uiComponents.tsxpackages/react/src/hooks/useAuth.tspackages/react/src/types.tspackages/shared/src/eventBus.tspackages/shared/src/react/billing/payment-element.tsxpackages/shared/src/react/hooks/createBillingPaginatedHook.tsxpackages/shared/src/react/hooks/useOrganization.tsxpackages/shared/src/react/hooks/useOrganizationCreationDefaults.types.tspackages/shared/src/react/hooks/useOrganizationList.tsxpackages/shared/src/react/hooks/usePaymentAttemptQuery.types.tspackages/shared/src/react/hooks/usePlanDetailsQuery.types.tspackages/shared/src/react/hooks/useStatementQuery.types.tspackages/shared/src/react/hooks/useSubscription.types.tspackages/shared/src/react/types.tspackages/shared/src/types/apiKeys.tspackages/shared/src/types/attributes.tspackages/shared/src/types/billing.tspackages/shared/src/types/clerk.tspackages/shared/src/types/client.tspackages/shared/src/types/factors.tspackages/shared/src/types/hooks.tspackages/shared/src/types/identifiers.tspackages/shared/src/types/image.tspackages/shared/src/types/instance.tspackages/shared/src/types/jwtv2.tspackages/shared/src/types/multiDomain.tspackages/shared/src/types/oauth.tspackages/shared/src/types/organization.tspackages/shared/src/types/organizationDomain.tspackages/shared/src/types/organizationInvitation.tspackages/shared/src/types/phoneCodeChannel.tspackages/shared/src/types/redirects.tspackages/shared/src/types/resource.tspackages/shared/src/types/session.tspackages/shared/src/types/signInFuture.tspackages/shared/src/types/signUpCommon.tspackages/shared/src/types/signUpFuture.tspackages/shared/src/types/strategies.tspackages/shared/src/types/telemetry.tspackages/shared/src/types/user.tspackages/shared/src/types/waitlist.tspackages/shared/src/types/web3.tspackages/ui/src/internal/appearance.tspackages/ui/src/styledSystem/StyleCacheProvider.tsxpackages/vue/src/plugin.tsscripts/renovate-config-generator.mjstsconfig.typedoc.jsonturbo.jsontypedoc.config.mjs
💤 Files with no reviewable changes (1)
- packages/clerk-js/src/core/resources/Client.ts
| /** | ||
| * Snapshots for `extract-methods.mjs` output. Each `.mdx` under `__snapshots__/` is a frozen copy of a representative file produced by `typedoc:generate`. Refactors to the plugin or its helpers should leave these files byte-identical; a diff means the change is observable in the published docs and needs a human decision. | ||
| * | ||
| * Run `pnpm typedoc:generate` first to populate `.typedoc/docs/`, then `vitest run` here. |
There was a problem hiding this comment.
Fix path inconsistency in setup instructions.
Line 8 says generated files are under .typedoc/docs/, but the test reads from docs (Line 25). Please align the comment with the actual DOCS_DIR path to avoid confusion while running snapshots.
🤖 Prompt for 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.
In @.typedoc/__tests__/extract-methods.test.ts at line 8, The comment header is
inconsistent with the actual DOCS_DIR used by the test; update the comment on
line 8 to match the real DOCS_DIR constant used in the test (referenced as
DOCS_DIR in the file) so it correctly instructs to run `pnpm typedoc:generate`
and points to the same output directory the test reads from (i.e., change
“.typedoc/docs/” to whatever DOCS_DIR equals, or change DOCS_DIR to match the
comment).
|
Actionable comments posted: 0 |
|
@jacekradko hey hey, got some scary warnings here from snapi but here's what my agent is telling me: this is a false positive caused by a recent snapi version bump on main, not anything in your PR.
Evidence:
- All 19 "removed" properties have an @internal JSDoc tag (verified locally)
- Your branch's source has them all (no removal in git diff main...HEAD)
- Your local build emits all 86 __internal_* symbols in dist/types/index.d.ts
- The snapi tool was bumped multiple times in the last 24h on main:
- a3740fca3c snapi bump + cache changes (yesterday)
- 17925fee39 enabled snapi AI reviewer
- e42b48eceb, 5283c8cb90, d679eb1e2b further bumps
- be63baad54 extended coverage to all SDK packages
The most likely cause: the new snapi version strips @internal-tagged symbols from the analyzed API, but the cached baseline (from before the bump) still includes them. Result: every @internal symbol appears as "removed" in any PR opened during this window.just wanna make sure i'm okay 😨 |
|
Actionable comments posted: 0 |
Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
|
Actionable comments posted: 0 |
Previously outputs were `.typedoc/**`, which caused turbo to capture and later restore `__tests__/__snapshots__/` files over committed updates, making snapshot edits invisible to CI. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
|
Actionable comments posted: 0 |
3 participants
Description
For the
/objectsin clerk-docs, we want to generate the reference information. In summary, this PR's main change is that:When typedoc goes to generate files, it creates a folder for each defined object (which we define in
reference-objects.mjs. E.g.clerkobject gets.typedoc/docs/shared/clerkfolder. This folder will have a<OBJECTNAME>-properties.mdxfile and a<OBJECTNAME>-methodsfolder that includes each of the methods.In a little more detail:
In
reference-objects.mjs, we define these objects by defining the Typedoc output paths and by defining the primary interface/class on each reference object page in order to resolve TypeDoc reflections.The
extract-methods.mjsscript will extract all of the methods from that object's primary interface/class and create a dedicated file for each one. I won't go into lengthy detail here, but the file is heavily commented through.In
custom-router.mjsREFERENCE_OBJECT_PAGE_SYMBOLS, dedicated folders are created for each object. Soclerk.mdxno longer gets added to.typedoc/docs/shared/, it gets added to its own folder:.typedoc/docs/shared/clerk/In
custom-plugin.mjsapplyRelativeLinkReplacements()helper that theextract-methods.mjsscript uses to incorporate the link replacements into the files it generatesapplyCatchAllMdReplacements()helper that theextract-methods.mjsscript uses to incorporate the catch-all replacements into the files it generatesstripReferenceObjectPropertiesSection()which removes the Properties section from a generated file and puts it into its own file. For example, ifshared/clerk/clerk.mdxis generated, it pulls the Properties section from it and puts it into its ownshared/clerk/clerk-properties.mdxfile.comment-utils.mjsis used as a helper to remove "TODO" and its following text from generated content.standalone-page-tag.mjsadds support for a custom tag called@standalonePagethat can be used in conjunction with the@inlinetag to indicate to typedoc to still generate a dedicated page for that type, even though it is recognized as@inline. Using both of these tags means that the type will show up as inlined in a table, but will also still have a generated MDX file.Adds support for a custom tag
@generateWithEmptyComment: self-documenting placeholder for declarations intentionally left without a description.Notable additions:
See the following examples (with before on left, after on right):
joinWaitlist(), it accepts a params object of typeJoinWaitlistParams. Instead of a "Parameters" section, it has a "JoinWaitlistParams" section:Checklist
pnpm testruns as expected.pnpm buildruns as expected.Type of change