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

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

我们可以有这样的东西

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

---

将为该

@runnableExample

代码生成某种自定义代码，该代码将插入名为

/examples/foo example.js

的文件。这只是一个关于良好用户体验的建议，但不是它需要的方式。

JSDoc CLI有一个有用的

-X

标志，您可以使用它来检查（和处理）注释中的元数据：

/**
*@return{number}
*/
函数答案（）{
返回42；
}

[
{
“注释”：“/**\n*@return{number}\n*/”，
“元”：{
“范围”：[
28,
62
],
“文件名”：“example.js”，
“行号”：4，
“columnno”：0，
“路径”：“/workspace/dev/tmp”，
“代码”：{
“id”：“ASTNODE10000002”，
“名称”：“答案”，
“类型”：“函数声明”，
“参数名称”：[]
}
},
“回报”：[
{
“类型”：{
“姓名”：[
“数字”
]
}
}
],
“名称”：“答案”，
“longname”：“答案”，
“种类”：“功能”，
“范围”：“全球”，
“参数”：[]
},
{
“种类”：“包装”，
“longname”：“包：未定义”，
“文件”：[
“/workspace/dev/tmp/example.js”
]
}
]

但是定制标签呢？

-X

标志也将处理它们：

/**
*@答案42
*/
函数答案（）{
返回42；
}

[
{
“评论”：“/**\n*@answer 42\n*/”，
“元”：{
“范围”：[
22,
56
],
“文件名”：“example.js”，
“行号”：4，
“columnno”：0，
“路径”：“/workspace/dev/tmp”，
“代码”：{
“id”：“ASTNODE10000002”，
“名称”：“答案”，
“类型”：“函数声明”，
“参数名称”：[]
}
},
“标签”：[
{
“原文”：“答案”，
“标题”：“答案”，
“案文”：“42”，
“值”：“42”
}
],
“名称”：“答案”，
“longname”：“答案”，
“种类”：“功能”，
“范围”：“全球”，
“参数”：[]
},
{
“种类”：“包装”，
“longname”：“包：未定义”，
“文件”：[
“/workspace/dev/tmp/example.js”
]
}
]

正如您所看到的，输出是纯JSON，这使得通过JavaScript或任何合适的模板系统进行处理非常容易。我已经放弃JSDoc模板很长一段时间了。我使用

jsdoc-X

并自己处理注释

最近我一直在玩JQ和EJS，并将结果反馈给Slate生成文档网站：-这是一个伪造API的文档网站

你想要达到的目标是绝对可行的。希望这足以让你开始。如果您想了解更多信息：

$ jsdoc -X tmp/example.js