docs(api/hooks): auto-generate docs for DOM-related hooks #13987
Conversation
|
| @@ -295,7 +296,9 @@ function writeMarkdownFile( | |||
| } | |||
|
|
|||
| // Create the filename (e.g., useHref.md) | |||
| const filename = `${comment.name}.md`; | |||
| const filename = `${ | |||
| comment.unstable ? comment.name.replace("unstable_", "") : comment.name | |||
There was a problem hiding this comment.
Needed for usePrompt docs
| @@ -313,7 +316,10 @@ function generateMarkdownForComment(comment: SimplifiedComment): string { | |||
|
|
|||
| // Title with frontmatter | |||
| markdown += `---\n`; | |||
| markdown += `title: ${comment.name}\n`; | |||
| markdown += `title: ${ | |||
| comment.unstable ? comment.name.replace("unstable_", "") : comment.name | |||
There was a problem hiding this comment.
Needed for usePrompt docs
| let name = unstable | ||
| ? comment.tags.find((t) => t.type === "name")?.string | ||
| : comment.ctx.name; |
There was a problem hiding this comment.
Needed for usePrompt docs
| let signature = getSignature(comment.code).replace( | ||
| unstable ? comment.ctx.name : "", | ||
| unstable ? name : "" | ||
| ); |
There was a problem hiding this comment.
Needed for usePrompt docs
| @@ -42,13 +53,12 @@ function SomeComponent() { | |||
| ## Signature | |||
|
|
|||
| ```tsx | |||
| useFetcher(options): FetcherWithComponents | |||
| useFetcher<T = any>({ key, }: {}) | |||
There was a problem hiding this comment.
Something seems off in the getSignature code when there are comments in the types 🤔
There was a problem hiding this comment.
That's a bummer - but we shouldn't need to inline document them anymore since we're now doing it at the @params tag
There was a problem hiding this comment.
I'll make these updates too 👍
| @@ -29,19 +40,16 @@ function SomeComponent() { | |||
| ## Signature | |||
|
|
|||
| ```tsx | |||
| useFormAction(action, __namedParameters): string | |||
| useFormAction() | |||
| @@ -52,46 +64,3 @@ useSearchParams([["tab", "1"]]); | |||
| useSearchParams(new URLSearchParams("?tab=1")); | |||
| ``` | |||
|
|
|||
| ## SetSearchParams Function | |||
There was a problem hiding this comment.
"SetSearchParams function" & "Notes" aren't really additional examples, so we probably need to think about a generic way to still include these parts?
There was a problem hiding this comment.
In these cases, when we want to inject content below the Example we can just skip the @example tag and inline the example manually and any additional subheadings directly in the main Summary. That allows us to include an example and then more stuff below it:
/**
* Returns a tuple of the current URL's [`URLSearchParams`](https://developer.mozilla.org/en-US/docs/Web/API/URLSearchParams)
* and a function to update them. Setting the search params causes a navigation.
*
* ```tsx 👈 Manual inline example allowing us to put more long form content after
* import { useSearchParams } from "react-router";
*
* export function SomeComponent() {
* const [searchParams, setSearchParams] = useSearchParams();
* // ...
* }
* ```
*
* ### SetSearchParams Function
* ...
There was a problem hiding this comment.
I made this change in my branch btw
There was a problem hiding this comment.
Looking at my changes in #13985, I changed the logic to not put a code block around the example if @example already contained ```
This was needed to get the note out of useRevalidator's example code block (see #13985 (comment))
I could just put the rest of the text in the example as well and already include the code block
|
Thanks! I had started on parts of this file too and began working on handling unstable APIs in the script so I'll copy the new JSDocs from this PR into my branch and get that PR'd up. The components (notably those using |
|
Superseded by #14002 |
Follow-up of #13963
I'm happy to revert 8301479 if you want it to be automatically done by the GitHub Workflow instead