时间戳

首页 > 解决方案 > 在JSDoc中，doclet的正确定义是什么？

javascript - 在JSDoc中，doclet的正确定义是什么？

问题描述

//Example 1
/**
 * This is a function that return a message
 * @param {String} msg The message that gonna be returned
 * @returns {String} The message 
 */
function myFunction(msg) {
  return msg
}

//Example 2
/**
 * This is a function that return a message
 * @function myFunction
 * @param {String} msg The message that gonna be returned
 * @returns {String} The message 
 */

拿上面的例子来说，你们能告诉我JSDoc中哪个是doclet吗？“依赖”函数显示在文档上的注释（示例 1）或显示在文档上而不“依赖”任何东西的注释（因为我给它自己的名字是myFunction）？

标签： javascriptjsdoc

解决方案

doclet 是暴露给插件和模板的 JSDoc 实体。大多数人处理的是 JSDoc 注释，例如，

所以.js

/**
 * This is a JSDoc comment
 */

转储 doclet：

# npx jsdoc -X so.js
[
    {
        "kind": "package",
        "longname": "package:undefined",
        "files": [
            "/workspace/dev/tmp/so.js"
        ]
    }
]

另一个例子：

/**
 * @return {boolean}
 */
function foo() {
  return true;
}

文档集：

# npx jsdoc -X so.js 
[
    {
        "comment": "/**\n * @return {boolean}\n */",
        "meta": {
            "range": [
                29,
                62
            ],
            "filename": "so.js",
            "lineno": 4,
            "columnno": 0,
            "path": "/workspace/dev/tmp",
            "code": {
                "id": "astnode100000002",
                "name": "foo",
                "type": "FunctionDeclaration",
                "paramnames": []
            }
        },
        "returns": [
            {
                "type": {
                    "names": [
                        "boolean"
                    ]
                }
            }
        ],
        "name": "foo",
        "longname": "foo",
        "kind": "function",
        "scope": "global",
        "params": []
    },
    {
        "kind": "package",
        "longname": "package:undefined",
        "files": [
            "/workspace/dev/tmp/so.js"
        ]
    }
]

如您所见，JSDoc 不需要您说这foo是一个函数。有很多信息可以从源代码中推断出来，并且这些信息被捕获在一个 doclet 中。

JSDoc 文档中有几个地方提到了“虚拟 JSDoc 注释”。这些是独立的 JSDoc 块，即不紧跟 JS 代码。事实上，您可以只使用虚拟 JSDoc 注释而根本不需要实际代码来生成完整的 API 文档。

推荐阅读