documentationjs / documentationjs/documentation

Add support for TSDoc-like @example syntax

Open
#1,277 1 comment 0 reactions 1 assignee Claimed by @anthony-redFox View on GitHub
Dominant language
JavaScript
Stars
5.8k
Forks
481
PR merge metrics
No merged PRs in 30d

Description

[API Extractor](https://api-extractor.com/), which is based upon [TSDoc](https://github.com/Microsoft/tsdoc), has implemented support for the `@example` annotation, but it only supports markdown-like syntax as follows:

```js
/**
* 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:

```md
##### 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.

Contributor guide

Open the contributing guide

Assessment

This issue has not been assessed yet.

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.