docs(backend,shared): Generate typedoc output for backend docs#8853
docs(backend,shared): Generate typedoc output for backend docs#8853alexisintech wants to merge 10 commits into
Conversation
Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
🦋 Changeset detectedLatest commit: 64f24dd The changes in this PR will be included in the next version bump. This PR includes changesets to release 0 packagesWhen 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 |
|
The latest updates on your projects. Learn more about Vercel for GitHub.
|
|
Important Review skippedDraft detected. Please check the settings in the CodeRabbit UI or the ⚙️ Run configurationConfiguration used: Repository YAML (base), Repository UI (inherited) Review profile: CHILL Plan: Pro Run ID: You can disable this status message by setting the Use the checkbox below for a quick retry:
Thanks 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 |
@clerk/astro
@clerk/backend
@clerk/chrome-extension
@clerk/clerk-js
@clerk/eslint-plugin
@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>
… MDX pages
- JSDoc all 24 public OrganizationAPI methods + their parameter types.
- Register `organization-api` in `.typedoc/reference-objects.mjs` `BACKEND_API_CONFIG`.
- Disambiguate the colliding `GetOrganization{Membership,Invitation}ListParams`
exports (user-scoped on `UserApi`, org-scoped on `OrganizationApi`) via an
explicit `export type { ... } from './UserApi'` in `endpoints/index.ts`.
UserApi's variants remain the canonical public exports; OrganizationApi's
exports stay reachable for direct imports and for typedoc.
- `.typedoc/extract-methods.mjs`:
- Resolve nested rows when a param type is `Array<{...}>` (e.g.
`CreateBulkOrganizationInvitationParams`) by unwrapping the array element
in `resolveDeclarationWithObjectMembers`.
- Append `?` to nested `params.field` rows for optional child properties,
matching the inline-`{ ... }` flatten behavior in `custom-theme.mjs`.
Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
…collision
ESLint's `import/export` rule flagged the `export *` from both UserApi and
OrganizationApi as a duplicate-export conflict on `GetOrganizationMembershipListParams`
and `GetOrganizationInvitationListParams`, and the earlier explicit `export type
{ ... } from './UserApi'` disambiguator only added a third source of the names.
Replace `export * from './OrganizationApi'` with an explicit enumeration that omits
the two colliders, so only UserApi's user-scoped variants reach the public barrel.
OrganizationApi's org-scoped variants stay exported from the file itself, reachable
via direct import and resolvable by typedoc on the class methods.
Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
|
@alexisintech Have just committed a small docs review - organization for the Organization stuff. It fixes two things:
See before 
See after 
Have noticed a few odd things but wanted to get your opinion first, so will post a separate comment for those on |
The `./src/api/endpoints/**/*.ts` glob in `packages/backend/typedoc.json` was silently expanding to zero files in CI (Linux + Node 24.15) while expanding correctly locally (macOS), producing `[warning] The glob ... did not match any files` and skipping backend extraction entirely. Replace the glob with an explicit file list to sidestep the environment-sensitive expansion. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
| "./src/api/endpoints/M2MTokenApi.ts", | ||
| "./src/api/endpoints/MachineApi.ts", | ||
| "./src/api/endpoints/OAuthApplicationsApi.ts", | ||
| "./src/api/endpoints/OrganizationApi.ts", |
There was a problem hiding this comment.
@alexisintech Adding both UserApi.ts and OrganizationApi.ts as Typedoc entrypoints produces standalone page collisions for shared param type names like GetOrganizationMembershipListParams and GetOrganizationInvitationListParams.
The generated output currently includes both the canonical file and a -1 variant, for example:
We could add a small post-processing step for these known endpoint param collisions so the generated files get stable scoped names (for example user-... vs organization-...) instead of leaking TypeDoc -1 suffixes into the public docs output?
So after Typedoc runs:
-
Detect the colliding generated pages
-
Rename them to stable names like:
user-get-organization-membership-list-params.mdx organization-get-organization-membership-list-params.mdx -
Rewrite generated links to use those names
| /** | ||
| * Gets the corresponding [OAuth access token](!oauth-access-token) for a user that has previously authenticated with the given OAuth provider. | ||
| * @param userId - The ID of the user to get the OAuth access tokens for. | ||
| * @param provider - The OAuth provider to get the access tokens for. If using a custom OAuth provider, prefix the provider name with `custom_` (e.g. `custom_google`). |
There was a problem hiding this comment.
@alexisintech Imo, the new description for provider looks a bit ambiguous next to the generated signature. The prose example says custom_google, but the rendered type resolves to oauth_custom_${string}, so I think it's easy to read the example as the full argument value rather than just the provider-name portion. Could we make the example explicit (for example oauth_custom_google) so the docs match the rendered signature more clearly?
|
@alexisintech have left a docs review - user for the User stuff. It fixes two things.
Also submitted a docs review - user in the Other than that, one issue I did find is the following:
Old live docs 
VS now 
|
2 participants
Summary
packages/backend/src/api/endpoints/**/*.@expandPropertiesmodifier tag (handled by.typedoc/custom-plugin.mjs) so generic-instantiation aliases likeUserListParams = ClerkPaginationRequest<{...}>render as a single merged properties table instead of an empty page. typedoc-plugin-markdown otherwise has no rendering branch for top-levelReferenceTypes. Tag applied toClerkPaginationRequestandClerkPaginationParams.extract-methods.mjspipeline via a newBACKEND_API_CONFIGin.typedoc/reference-objects.mjs. Each endpoint class registered here gets abackend/<kebab-name>/folder containing<name>.mdx(main page) andmethods/<method>.mdx(one file per public method, with description + TypeScript signature + parameters).extract-methods.mjsnow supports two output styles via amethodFormatoption plumbed from the config:reference(existing reference-object pages — Clerk, UserResource, etc.):### foo()title +#### Parametersheading. Designed for pages aggregating many methods.page(new, used byBACKEND_API_CONFIG): no method-name title,## Parametersheading. Designed for one-method-per-docs-page consumption.getPrimaryCallSignatureskips@deprecatedoverloads (preferring the canonical signature when multiple are exposed).parametersMarkdownTableoverlays@paramblock tags fromsig.commentonto each parameter when their own comment is missing — fixes overloaded methods where the implementation's JSDoc carries the descriptions but typedoc only wires them onto the hidden implementation signature, leaving overloads with no per-parameter descriptions.nestedParameterRowsFromDocumentedPropertiesstrips line breaks in the description column, so JSDoc descriptions containing<ul>blocks no longer shatter the markdown table.resolveDeclarationWithObjectMembersnow unwrapsArrayType.elementTypesoparams: Array<{...}>(e.g.CreateBulkOrganizationInvitationParams) flattens into nestedparams.*rows instead of dumping the inline shape into the Type column.formatNestedParamNameColumnnow appends?to nested rows when the child property is optional (read fromchild.flags?.isOptional) — matches the inline-{ ... }flatten behavior inclerkParametersTable.flattenParams. Retroactively adds?markers to previously-incorrect rows likeupdate-user.mdx'sparams.backupCodes?,params.firstName?, etc.