问题描述
我们正在重写我们的 API 文档,我们希望将自定义内容添加到我们生成的 JSDoc 中。例如,此自定义内容可以是可运行的代码片段,这是我们目前在手动编写的文档中具有的功能(基于 Jekyll 注入动态内容)。有没有办法直接实现这一点,使用 JSDoc 的模板系统和一些今天的自定义代码,或者通过对生成的 html 进行后处理以寻找某种符号来间接?其他可以处理此问题的 JSDoc 生成器也很有趣。
比如说,我们可以有这样的东西
/**
* @param {String} foo
* @runnableExample foo-example
*/
将为该 @runnableExample
代码生成某种自定义代码,该代码将插入一个名为 ./examples/foo-example.js
的文件。这只是对良好用户体验的建议,而不是必须的。
解决方法
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"
]
}
}
],"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
],"tags": [
{
"originalTitle": "answer","title": "answer","text": "42","value": "42"
}
],"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