JSDoc 不显示 table 个参数和 return value/name/description

Question

我已经开始为我的项目实现 JSDoc，根据文档，函数 header 如下所示：

/**
 * @name randomlyGenerateMixedCaseLetterOrSpecialCharacter1
 * @description Randomly generates an alphabetic letter from A-Z, a-z or a random special character from the input list of special characters.
 * @param {string} inputData - The list of allowable special characters that should be used to randomly select from.
 * @param {string} inputMetaData - Not used for this business rule.
 * @return {string} Randomly returns a random mixed case letter of the alphabet, or a random special character from the list of allowable special characters.
 * @NOTE: OLD implementation.
 * @author Seth Hollingsead
 * @date 2020/03/05
 */

应该生成一个小 table:

-----------------------------------------------------
|   Name        |  Type  |       Description        |
-----------------------------------------------------
| inputData     | String | The list of allowable... |
| inputMetaData | String | Not used for this...     |
-----------------------------------------------------

但是当我运行 JSDoc 针对此函数时，它输出的内容更像这样：

randomlyGenerateMixedCaseLetterOrSpecialCharacter1
Randomly generates an alphabetic letter from A-Z, a-z or a random special character from the input list of special characters.

Author:
Seth Hollingsead
Source:
Framework/BusinessRules/Rules/characterGeneration.js, line 18

它完全缺少 @param 和 @return 标签。

这是完整的函数，减去了 body。也许是我声明函数的方式？

/**
 * @name randomlyGenerateMixedCaseLetterOrSpecialCharacter1
 * @description Randomly generates an alphabetic letter from A-Z, a-z or a random special character from the input list of special characters.
 * @param {string} inputData - The list of allowable special characters that should be used to randomly select from.
 * @param {string} inputMetaData - Not used for this business rule.
 * @return {string} Randomly returns a random mixed case letter of the alphabet, or a random special character from the list of allowable special characters.
 * @NOTE: OLD implementation.
 * @author Seth Hollingsead
 * @date 2020/03/05
 */
export const randomlyGenerateMixedCaseLetterOrSpecialCharacter1 = function(inputData, inputMetaData) {
  // ...Function Body...
};

这是我的 jsdoc.json 文件：

{
  "source": {
    "include": ["src"],
    "includePattern": ".js$",
    "excludePattern": "{node_modules/|Documentation}"
  },
  "plugins": ["plugins/markdown"],
  "templates": {
    "cleverLinks": true,
    "monospaceLinks": true
  },
  "opts": {
    "recurse": true,
    "destination": "./src/Application/NodeJS-App/Resources/Documentation",
    "template": "./jsDocTemplate"
  }
}

查看错误日志，我没有在这一行看到该文件的任何错误。当然，我确实看到了其他函数的错误，但这只是因为我没有正确更改 header 的格式。例如：（我知道这是不正确的，但这是我知道我仍然需要做的事情的一个例子:)

/**
 * @name randomlyGenerateUpperCaseLetterOrSpecialCharacter1
 * @description Randomly generates an alphabetic letter from A-Z or a random special character from the input list of special characters.
 * @param  {[String]} inputData The list of allowable special characters that should be used to randomly select from.
 * @param  {[String]} inputMetaData Not used for this business rule.
 * @return {[String]} Randomly returns a random upper case letter of the alphabet, or a random special character from the list of allowable special characters.
 * @NOTE: OLD implementation.
 * @author Seth Hollingsead
 * @date 2020/03/05
 */
export const randomlyGenerateUpperCaseLetterOrSpecialCharacter1 = function(inputData, inputMetaData) {
  // ... function body
};

在上面的header中，@param {[String]}应该改为@param {string}，我还有很多函数可以用，我只是想确保我做对了在我擦除所有文件中的所有功能之前。

我得到的错误是这样的：（虽然实际错误有点冗长）

\src\Framework\BusinessRules\Rules\characterGeneration.js in line 70 with tag title "param" and text "{[String]} inputData The list of allowable special characters that should be used
\src\Framework\BusinessRules\Rules\characterGeneration.js in line 70 with tag title "param" and text "{[String]} inputMetaData Not used for this business rule.": Invalid type expression "[
\src\Framework\BusinessRules\Rules\characterGeneration.js in line 70 with tag title "return" and text "{[String]} Randomly returns a random upper case letter of the alphabet, or a random special character

但正如我所说，即使在更正后我仍然没有从标签中获得 meta-information 的 @param & @returns table。

编辑：版本号：

npm 版本：6.9.0
节点版本：10.16.3
"jsdoc": "^3.6.4",

有什么想法吗？

提前致谢！！干杯并注意安全！！

更新：我能够让它为我的一个功能工作，所以我想我现在的问题是为什么它对一个功能有效但对其他功能无效？

这里是 header 的函数，我能够让它工作：

/**
 * Converts a time interval into a different kind of format.
 * @param {integer} deltaTime - A time interval measured in microseconds.
 * @param {string} format - The formatting template that should be used to format the time interval.
 * @return {string} A time interval formatted according to the input format template string.
 * @author Seth Hollingsead
 * @date 2020/05/21
 */
function reformatDeltaTime(deltaTime, format) {
  // ... function body...
}

此外，当相同的函数 header 如下所示时：

/**
 * @name reformatDeltaTime
 * @description Converts a time interval into a different kind of format.
 * @param {integer} deltaTime - A time interval measured in microseconds.
 * @param {string} format - The formatting template that should be used to format the time interval.
 * @return {string} A time interval formatted according to the input format template string.
 * @author Seth Hollingsead
 * @date 2020/05/21
 */
function reformatDeltaTime(deltaTime, format) {
  // ...function body
}

它不起作用，但据说 JSDocs 应该支持 @name 和 @description 标签？那么给出了什么？我又一次 re-iterate...为什么是一种 header 格式而不是另一种？我是否可以进行任何配置更改以使用 @name 和 @description 标签支持 header？

Answer 1

哇，好吧，我想我需要多读一点文档。永远是个好主意....大声笑

Copy-pasted 来自 JSDoc 文档： Link: JSDoc @Name Tage Usage

The @name tag forces JSDoc to associate the remainder of the JSDoc comment with the given name, ignoring all surrounding code. This tag is best used in "virtual comments" for symbols that are not readily visible in the code, such as methods that are generated at runtime.

When you use the @name tag, you must provide additional tags that tell JSDoc what kind of symbol you are documenting; whether the symbol is a member of another symbol; and so on. If you do not provide this information, the symbol will not be documented correctly.

Warning: By using the @name tag, you are telling JSDoc to ignore the surrounding code and treat your documentation comment in isolation. In many cases, it is best to use the @alias tag instead, which changes a symbol's name in the documentation but preserves other information about the symbol.

所以我刚刚删除了@name 标签，它对我常用的函数 header 正常工作，看起来像这样：

/**
 * @description Returns a time stamp string formatted according to the input formatting string.
 * @param {string} formatting The formatting string, that tells moment in what format to return the value for the day, month, year, hour, minute, and second.
 * @return {string} A time stamp string that has been formatted according to the input format.
 * @author Seth Hollingsead
 * @date 2020/05/21
 */
function getNowMoment(formatting) {
  // ...function body...
};

但是，它仍然不适用于这样定义的函数：

export const generateRandomMixedCaseTextByLength1 = function(inputData, inputMetaData) {
  // ...function body...
};

显然解决这个问题的方法是使用 @function 标签代替 @name 标签。 JSDoc 文档中对此进行了描述：@function tag documentation

因此本文档的 header 应如下所示：

/**
 * @function generateRandomMixedCaseTextByLength1
 * @description Parse the input string, and determine how many mixed case alphabetic characters should be generated, generate them and string them together.
 * @param {string} inputData The string that contains a number or how many randomly generated mixed case alphabetic characters should be generated.
 * @param {string} inputMetaData Not used for this business rule.
 * @return {string} A string of randomly generated mixed case letters where the length of the string is defined by the input parameter.
 * @NOTE: OLD implementation
 * @author Seth Hollingsead
 * @date 2020/03/04
 */

Answer 2

有同样的问题！

TLDR；

解决方案是在文件开头添加@module。 https://jsdoc.app/howto-es2015-modules.html

长答案：

所以如果你这样写你的模块：

module.export = {
/** 
* @description some Function
* @param none 
*/
someFunction {},
/** 
* @description some Function
* @param none 
*/
someOtherFunction {}
}

Jsdoc不理解你实现的功能。 @function 没有帮助我。

在文件开头添加行

/** @module someFunctions */

会告诉jsdoc文档是针对模块的，jsdoc会生成函数描述。

这个问题也可以通过定义函数并导出它们来解决。

Answer 3

@重复：

有同样的问题！

TLDR;

解决方案是在文件开头添加@module。 https://jsdoc.app/howto-es2015-modules.html

长答案：

所以如果你这样写你的模块：

module.export = {
/** 
* @description some Function
* @param none 
*/
someFunction {},
/** 
* @description some Function
* @param none 
*/
someOtherFunction {}
}

Jsdoc不理解你实现的功能。 @function 没有帮助我。

在文件开头添加行

/** @module someFunctions */

会告诉jsdoc文档是针对某个模块的，jsdoc会生成函数描述。

这个问题也可以通过定义函数并导出它们来解决。

JSDoc 不显示 table 个参数和 return value/name/description

JSDoc doesn't display a table of arguments and return value/name/description

javascript

node.js

jsdoc

ecmascript-6