@ng-prism/plugin-jsdoc 21.0.0 → 21.0.2
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/README.md +75 -0
- package/package.json +1 -1
package/README.md
ADDED
|
@@ -0,0 +1,75 @@
|
|
|
1
|
+
# @ng-prism/plugin-jsdoc
|
|
2
|
+
|
|
3
|
+
API documentation plugin for [@ng-prism/core](https://github.com/dyingangel666/ng-prism). Extracts JSDoc comments from component source code at build time and renders an interactive API panel.
|
|
4
|
+
|
|
5
|
+
> **Full documentation:** [ng-prism Docs — JSDoc Plugin](https://dyingangel666.github.io/ng-prism/#/plugins/jsdoc)
|
|
6
|
+
|
|
7
|
+
## Installation
|
|
8
|
+
|
|
9
|
+
```bash
|
|
10
|
+
npm install @ng-prism/plugin-jsdoc
|
|
11
|
+
```
|
|
12
|
+
|
|
13
|
+
### Peer Dependencies
|
|
14
|
+
|
|
15
|
+
| Package | Version |
|
|
16
|
+
|---|---|
|
|
17
|
+
| `@ng-prism/core` | `>=21.0.0` |
|
|
18
|
+
| `@angular/core` | `>=20.0.0` |
|
|
19
|
+
| `typescript` | `>=5.5.0` |
|
|
20
|
+
| `highlight.js` | `>=11.0.0` |
|
|
21
|
+
| `ngx-highlightjs` | `>=14.0.0` |
|
|
22
|
+
|
|
23
|
+
## Setup
|
|
24
|
+
|
|
25
|
+
```typescript
|
|
26
|
+
// ng-prism.config.ts
|
|
27
|
+
import { defineConfig } from '@ng-prism/core/config';
|
|
28
|
+
import { jsDocPlugin } from '@ng-prism/plugin-jsdoc';
|
|
29
|
+
|
|
30
|
+
export default defineConfig({
|
|
31
|
+
plugins: [jsDocPlugin()],
|
|
32
|
+
});
|
|
33
|
+
```
|
|
34
|
+
|
|
35
|
+
## What It Does
|
|
36
|
+
|
|
37
|
+
- Extracts class-level JSDoc description
|
|
38
|
+
- Extracts per-input and per-output JSDoc comments
|
|
39
|
+
- Renders an **API** panel with:
|
|
40
|
+
- Component description
|
|
41
|
+
- Inputs table (name, type, default, description)
|
|
42
|
+
- Outputs table (name, description)
|
|
43
|
+
- Supported tags: `@deprecated`, `@since`, `@see`, `@example`
|
|
44
|
+
|
|
45
|
+
## Example
|
|
46
|
+
|
|
47
|
+
```typescript
|
|
48
|
+
/**
|
|
49
|
+
* A configurable button for primary user actions.
|
|
50
|
+
*
|
|
51
|
+
* @since 2.0.0
|
|
52
|
+
* @see https://design-system.example.com/button
|
|
53
|
+
*/
|
|
54
|
+
@Showcase({ title: 'Button', category: 'Atoms' })
|
|
55
|
+
@Component({ selector: 'my-button', ... })
|
|
56
|
+
export class ButtonComponent {
|
|
57
|
+
/** Visual style variant of the button. */
|
|
58
|
+
variant = input<'primary' | 'secondary'>('primary');
|
|
59
|
+
|
|
60
|
+
/** Emitted when the button is clicked. */
|
|
61
|
+
clicked = output<void>();
|
|
62
|
+
}
|
|
63
|
+
```
|
|
64
|
+
|
|
65
|
+
The API panel shows the class description, a table of inputs with their types and JSDoc, and all supported tags.
|
|
66
|
+
|
|
67
|
+
## How It Works
|
|
68
|
+
|
|
69
|
+
**Build time:** The `onComponentScanned` hook uses `ts.createSourceFile` with `setParentNodes: true` and `ts.getJSDocTags()` to extract JSDoc data. The extracted data is injected into `showcaseConfig.meta.jsdoc`.
|
|
70
|
+
|
|
71
|
+
**Runtime:** The `JsDocPanelComponent` reads the metadata and renders the documentation. The component is lazy-loaded via `loadComponent`.
|
|
72
|
+
|
|
73
|
+
## License
|
|
74
|
+
|
|
75
|
+
MIT
|