documentation
documentation copied to clipboard
Add support for TSDoc-like @example syntax
API Extractor, which is based upon TSDoc, has implemented support for the @example annotation, but it only supports markdown-like syntax as follows:
/**
* Tracks acceleration and rotation rate of the device.
*
* @example
* ```tsx
* const Example = () => {
* const { acceleration, rotationRate, interval } = useDeviceMotion();
* // ...
* };
* ```
*/
Although this works with API Extractor, unfortunately, the markdown generator of documentation.js produces the following, invalid output:
##### Examples
````javascript
```tsx
const Example = () => {
const { acceleration, rotationRate, interval } = useDeviceMotion();
// ...
};
```;
````
This might be resolved by making the coding language annotation optional, defaulting to javascript when omitted.
That's unfortunate - if they had chosen to use Markdown syntax in the comment description, it would have been compatible with JSDoc – or if they had just used the old example style. But this is non-backwards-compatible and would require an extra configuration flag.