chore(shared,clerk-react,types): Improve Typedoc #5372
Conversation
|
The latest updates on your projects. Learn more about Vercel for Git ↗︎
|
🦋 Changeset detectedLatest commit: f108423 The changes in this PR will be included in the next version bump. This PR includes changesets to release 22 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 |
| /** | ||
| * A list of files where we want to remove any headings | ||
| */ | ||
| const FILES_WITHOUT_HEADINGS = [ |
There was a problem hiding this comment.
Some of the files only contain the contents of a single interface.
For example:
# Parameters
Table goes hereSo since I want to use the table contents as a partial/include somewhere else I need to get rid off the heading. But since I don't want to remove headings everywhere I'm removing them only from the files I want to use in such way.
| /** | ||
| * An array of tuples where the first element is the file name and the second element is the new path. | ||
| */ | ||
| const LINK_REPLACEMENTS = [ |
There was a problem hiding this comment.
Sometimes there are relative links like [PaginatedResponse](../types/paginated-response.mdx) in the files. The link to the also generated file through typedoc. But we already have that page manually created and want to link to it. So this replaces relative links with links to our existing docs.
| @@ -0,0 +1,43 @@ | |||
| <!-- #region nextjs-01 --> | |||
There was a problem hiding this comment.
In order to use the https://typedoc.org/documents/Tags.__include_.html flag the examples should be in the root of the package, so that relative links work for the files inside dist. Because it has to be resolved from dist to that folder.
| * | ||
| * The following example demonstrates how to use the `useAuth()` hook to access the current auth state, like whether the user is signed in or not. It also includes a basic example for using the `getToken()` method to retrieve a session token for fetching data from an external resource. | ||
| * | ||
| * <Tabs items='React,Next.js'> |
There was a problem hiding this comment.
If you use these MDX components (they are not resolved, just passed along) in such way, they won't be rendered in IntelliSense
| * ``` | ||
| */ | ||
| export const useOrganization: UseOrganization = params => { | ||
| export function useOrganization<T extends UseOrganizationParams>(params?: T): UseOrganizationReturn<T> { |
There was a problem hiding this comment.
No behavior change, just removing a type alias and explicitly making it a function (sometimes typedoc can be tripped up by using a const for a function)
| /** | ||
| * @interface | ||
| */ | ||
| export type UseOrganizationParams = { |
There was a problem hiding this comment.
Inside useOrganization and useOrganizationList you'll notice that I added export to the params and return types. I need those to be accessible to typedoc, which requires you to export them.
Since we don't re-export them from src/react/hooks/index.ts file they won't surface to the users.
| { | ||
| "$schema": "https://typedoc.org/schema.json", | ||
| "entryPoints": ["./src/index.ts", "./src/react/index.ts", "./src/react/types.ts"], | ||
| "entryPoints": ["./src/index.ts", "./src/react/types.ts", "./src/react/hooks/*.{ts,tsx}"], |
There was a problem hiding this comment.
I needed access to the exported interfaces inside useOrganization/useOrganizationList but didn't want to change the public API. So we're looking at the hooks individually now.
packages/react/.gitignore
Outdated
| @@ -1,2 +1,3 @@ | |||
| /*/ | |||
| !/src/ | |||
| !/examples/ | |||
There was a problem hiding this comment.
Can we rename to doc-examples, or simply docs ?
There was a problem hiding this comment.
Yeah, we can choose whatever name we want really. I'd probably pick docs then
| * | ||
| * The following example uses the `useSession()` hook to access the `Session` object, which has the `lastActiveAt` property. The `lastActiveAt` property is a `Date` object used to show the time the session was last active. | ||
| * | ||
| * <Tabs items='React,Next.js'> |
There was a problem hiding this comment.
Could this be items='react,next' ?
There was a problem hiding this comment.
In our existing docs we use <Tabs items={['React', 'Next.js'}]>. After the transformation to add the curly and square brackets it needs to be the same, hence it's written like that
LekoArts
deleted the
lekoarts/eco-508-finish-up-last-missing-pieces-for-react-hooks
branch
Description
TL;DR: Improve the JSDoc comments of all React hooks and add additional Next.js examples to some of them. Modify the MDX output so that it can be used for rendering on clerk.com/docs
{@include}JSDoc comments to add additional examplesFixes ECO-508
Fixes ECO-424
Checklist
pnpm testruns as expected.pnpm buildruns as expected.Type of change