documentation

documentation copied to clipboard

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.