Tsdoc: Is tsdoc going to support generating React component API?

[yuqingc]

Say there is a file like this

interface IProps {
   /**
    * Some description
    */
    name: string;
}
class Something extends React.Component<IProps, {}> {
    // code
}

Is tsdoc going to support generating React component API doc (eg, a markdown table)?

[TomasHubelbauer]

React components are initialized based on a call toReact.createElement, not by doing new MyComponent (at least not explicitly) or myComponent.prop = 'value' so what documentation fields exactly should be generated where? React.createElement will pick up the props type/interface in its second argument, so TSDoc you place on the props type's/interface's members will show up in Intellisense there.

Can you give an example of what would be generated based on the code you provided so far?

[yuqingc]

possibly something like this.

| Props | Type | Requied | Description |
| ------ | ------------------- | ------------ | -
| name | string | yes | Some descriptioin

or something JavaScript object like this

{
    propName: "name",
    type: "string",
    isRequired: true,
    default: "Someone",
    description: "..."
}

@TomasHubelbauer

[TomasHubelbauer]

But where? On the component class? On its constructor? Or do you have in mind generating documentation files (for example MarkDown) form TSDoc documentation comments?

[yuqingc]

Generating markdown would be nice. ref: like jsdoc-to-markdown

But where? On the component class? On its constructor? Or do you have in mind generating documentation files (for example MarkDown) form TSDoc documentation comments?

[TomasHubelbauer]

Now I understand. I think that's out of the scope for TSDoc itself (similarly to your link being a tool on top of JSDoc not a feature of JSDoc itself). Perhaps it would be good to ask jsdoc-to-markdown if they will add support for TSDoc.

[octogonz]

FYI this summer we are planning to enable API Extractor analysis for the office-ui-fabric-react library, which is a collection of React controls.

As far as I know, a documentation tool can model React controls as ordinary TypeScript classes and interfaces. If there are specific TSX features that you think would need special handling in the doc comment syntax, this would be in scope for TSDoc.

[octogonz]

Closing this because it seems like the questions were answered. Feel free to reopen if anyone wants to continue the discussion.

[trusktr]

FWIW, one can write a tsdoc comment on the props property, which links to the Props interface, and the docs for that interface can have all the info.