向生成的 JSDoc 文档添加自定义内容答案

【问题标题】：Adding custom content to generated JSDoc docs向生成的 JSDoc 文档添加自定义内容
【发布时间】：2021-05-31 21:35:58
【问题描述】：

我们正在重写我们的 API 文档，我们希望将自定义内容添加到我们生成的 JSDocs 中。例如，此自定义内容可以是可运行的 sn-ps 代码，这是我们目前在手动编写的文档中拥有的功能（基于 Jekyll 注入动态内容）。有没有办法直接实现这一点，使用 JSDoc 的模板系统和今天的一些自定义代码，或者通过对生成的 html 进行后处理来寻找某种符号间接？其他可以处理这个问题的 JSDoc 生成器也很有趣。

说，我们可以有这样的东西

/**
 * @param {String} foo
 * @runnableExample foo-example
 */

将为@runnableExample 代码生成某种自定义代码，该代码将插入一个名为./examples/foo-example.js 的文件。这只是对良好用户体验的建议，而不是它需要的方式。

【问题讨论】：

标签： jsdoc jsdoc3 jsdoc2md

【解决方案1】：

JSDoc CLI 有一个有用的-X 标志，您可以使用它来检查（和处理）注释中的元数据：

/**
 * @return {number}
 */
function answer() {
  return 42;
}

$ jsdoc -X tmp/example.js

[
    {
        "comment": "/**\n * @return {number}\n */",
        "meta": {
            "range": [
                28,
                62
            ],
            "filename": "example.js",
            "lineno": 4,
            "columnno": 0,
            "path": "/workspace/dev/tmp",
            "code": {
                "id": "astnode100000002",
                "name": "answer",
                "type": "FunctionDeclaration",
                "paramnames": []
            }
        },
        "returns": [
            {
                "type": {
                    "names": [
                        "number"
                    ]
                }
            }
        ],
        "name": "answer",
        "longname": "answer",
        "kind": "function",
        "scope": "global",
        "params": []
    },
    {
        "kind": "package",
        "longname": "package:undefined",
        "files": [
            "/workspace/dev/tmp/example.js"
        ]
    }
]

但是自定义标签呢？ -X 标志也会处理它们：

/**
 * @answer 42
 */
function answer() {
  return 42;
}

[
    {
        "comment": "/**\n * @answer 42\n */",
        "meta": {
            "range": [
                22,
                56
            ],
            "filename": "example.js",
            "lineno": 4,
            "columnno": 0,
            "path": "/workspace/dev/tmp",
            "code": {
                "id": "astnode100000002",
                "name": "answer",
                "type": "FunctionDeclaration",
                "paramnames": []
            }
        },
        "tags": [
            {
                "originalTitle": "answer",
                "title": "answer",
                "text": "42",
                "value": "42"
            }
        ],
        "name": "answer",
        "longname": "answer",
        "kind": "function",
        "scope": "global",
        "params": []
    },
    {
        "kind": "package",
        "longname": "package:undefined",
        "files": [
            "/workspace/dev/tmp/example.js"
        ]
    }
]

如您所见，输出是纯 JSON，这使得通过 JavaScript 或任何体面的模板系统进行处理变得非常容易。我已经放弃 JSDoc 模板很久了。我使用jsdoc -X 并自己处理注释。

最近我一直在玩 JQ 和 EJS，并将结果提供给 Slate 以生成文档网站：https://customcommander.github.io/project-blueprint/#project-blueprint-fake-api — 这是一个虚假 API 的文档网站。

您想要实现的目标绝对是可行的。希望这足以让您入门。想了解更多：https://github.com/customcommander/project-blueprint

【讨论】：