Fixes to support Generating API Documentation #4391
Conversation
this fixes an error when generating API documentation which prevents an documentation index page from being created
|
|
This pull request is automatically built and testable in CodeSandbox. To see build info of the built libraries, click here or the icon next to each commit SHA. Latest deployment of this branch, based on commit c9e9b6e:
|
| @@ -284,6 +287,8 @@ export interface StateValueMap { | |||
| /** | |||
| * The string or object representing the state value relative to the parent state node. | |||
| * | |||
| * @remarks | |||
There was a problem hiding this comment.
I'm still quite unsure why we need this. RxJS has extensive and long JSDocs and they use api-extractor too but there is no @remarks in sight in their codebase. I wonder what's the difference? 🤔
There was a problem hiding this comment.
On the index page a description is provided for each item.
With @remarks, we can choose to show only the first summary line in the descriptions:
Without @remarks, the description is longer (and most of the index descriptions are a single line so this one stands out):
So it’s a subjective change, but I thought it was better to have a shorter description. If you disagree I’m happy to change it back.
I had also noticed the list items weren’t formatted properly on the index, so I wanted to omit them, but I just found a fix for that I can push to this PR, so it's not a deciding factor.
There was a problem hiding this comment.
According to the API Extractor docs, it expects TSDoc and @remarks is specific to TSDoc, which explains why you wouldn’t see it in JSDocs. See: https://tsdoc.org/pages/tags/remarks
I’m curious about how RxJS docs are set up though. I’ll take a look.
There was a problem hiding this comment.
Hm, OK - so actually RxJS is not using the api-extractor (my memory is failing me). I agree that a shorter summary in this table is better but I really wish that we wouldn't have to use @remarks for this. Despite TSDoc being a Microsoft project, VS Code doesn't handle those TSDoc tags nicely 🤷♂️
I'm fine either way though - we can always revisit this in the future. I just feel that the primary use case for those JSDoc comments is the in-IDE experience and the API docs page generation comes second. We have some level of control over how API docs end up being generated as we can script whatever we want - we have 0 control over how an IDE renders its tooltips (beyond what we can configure using the JSDoC tags that it knows and understands)
There was a problem hiding this comment.
That's a good point. I’ll see what I can find out about TSDocs in VS Code. Might be some ways to improve the experience.
packages/core/src/types.ts
Outdated
| @@ -835,7 +841,7 @@ export interface StateNodeConfig< | |||
| TDelay | |||
| >; | |||
| /** | |||
| * @private | |||
| * @internal | |||
There was a problem hiding this comment.
We are using stripInternal and I'm not sure if we want to "hide" this parent property like this. I'd remove this particular comment completely.
Companion PR for statelyai/docs#237, which now uses
xstateas a submodule, and requires these changes in order to build API docs.This PR fixes issues that prevented the XState API docs index page from rendering properly, and fixes two warnings that occurred when API Documenter ran.
Includes and closes #4374