使用 jsdoc 完成模板组件的文档，特别是组件描述？

Question

我正在使用 stencil.js 创建 Web 组件库。我想利用 docs-readme 输出功能，但我不得不对哪些注释实际输出到文档中进行大量试验和错误。

我现在遇到的具体问题是，我无法获取组件本身的文档以使用自述文件生成。例如：

/**
 * This is a description of the component that I would like to generate in the readme.md for MyComponent
 */
@Component({
  tag: 'my-component',
  styleUrl: 'my-component.css',  
  shadow: true,
})
/** I've also tried this comment style and this location, but no dice */
export class MyComponent {
   ...
}

根据 jsdoc documentation 看来我应该能够记录 class，但似乎没有任何效果。是否有关于 stencil 会和不会实际生成文档的详尽列表？

Answer 1

您需要将 Web 组件（元素 class）本身的文档放置到（部分）生成的 readme.md。源文件（.tsx、.css）中只需要 class 成员（properties/attributes、方法）和 CSS 变量的文档。

(更新：有关组件注释的用途，请参阅下面的更新部分。)

将文档插入到以下行上方的 src/components/my-component/readme.md：

<!-- Auto Generated Below -->

此行下方的内容将使用源文件中的 JSDoc 注释生成。

例子

# x-eyes

Shows a pair of eyes following movements of ...

<!-- Auto Generated Below -->

见上例full readme, TS source and CSS source。

更新

实际上，如果您按预期向组件添加文档注释：

/**
 * Alternative summary...
 */
@Component({ tag: 'x-eyes', styleUrl: 'x-eyes.css' })
export class XEyesElement {

它将被使用，但是 docs-json 或 docs-vscode 输出目标的 not in the readme file; but only in the docs property：

{
  "filePath": "./src/components/x-eyes/x-eyes.tsx",
  "encapsulation": "shadow",
  "tag": "x-eyes",
  "docs": "Alternative summary...",
  "readme": "# &lt;x-eyes&gt;\n\nShows a pair of eyes following movements ...

如果您不向组件添加文档注释，docs 属性的内容将从您的 readme.md 的第一部分提取，在主标题之间和第一个 sub-title（由 # 发起）：

{
  "filePath": "./src/components/x-eyes/x-eyes.tsx",
  "encapsulation": "shadow",
  "tag": "x-eyes",
  "docs": "Shows a pair of eyes following movements of ...",
  "readme": "# &lt;x-eyes&gt;\n\nShows a pair of eyes following movements ...

因此，如果您想将组件的描述摘要更改为比 readme.md 的介绍部分更短或不同，您可以将组件注释插入组件源。

使用 jsdoc 完成模板组件的文档，特别是组件描述？

Complete documentation for stencil components with jsdoc, specifically a component description?

jsdoc

stenciljs

例子

更新