JSDoc 不显示参数表和返回值/名称/描述

Question

我已经开始为我的项目实现 JSDoc，并且根据文档，函数头是这样的：

/**
 * @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
 */

应该生成一个小表：

-----------------------------------------------------
|   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 标签。

这是完整的功能，减去身体。也许是我声明函数的方式？

/**
 * @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"
  }
}

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

/**
 * @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
};

在上面的标题中，@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

但正如我所说，即使在更正之后，我仍然没有从标签中获得 @param 和 @returns 元信息表。

---

编辑：版本号：

• npm 版本：6.9.0
• 节点版本：10.16.3
• “jsdoc”：“^3.6.4”，

有什么想法吗？

提前谢谢你！！ 干杯并保持安全！

---

更新：我能够让它适用于我的一个功能，所以我想我现在的问题是为什么它适用于一个功能而不适用于其他功能？

这是我能够使其工作的函数的标题：

/**
 * 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...
}

另外，当相同的函数头看起来像这样时：

/**
 * @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标签？那么给了什么？我再次重复......为什么一种标题格式而不是另一种？我可以进行任何配置更改以支持带有@name 和@description 标签的标头吗？

Answer 1

哇，好吧，我想我需要阅读更多有关文档的内容。总是一个好主意....大声笑

从 JSDoc 文档中复制粘贴： 链接：JSDoc @Name Tage Usage

@name 标记强制 JSDoc 将 JSDoc 注释的其余部分与给定名称相关联，忽略所有周围的代码。此标记最适合在“虚拟 cmets”中用于在代码中不易看到的符号，例如在运行时生成的方法。

当你使用@name 标签时，你必须提供额外的标签来告诉JSDoc你正在记录什么样的符号；该符号是否是另一个符号的成员；等等。如果您不提供此信息，则符号将无法正确记录。

警告：通过使用@name 标记，您是在告诉 JSDoc 忽略周围的代码并单独处理您的文档注释。在许多情况下，最好改用@alias 标签，它会更改文档中符号的名称，但会保留有关符号的其他信息。

所以我刚刚删除了@name 标记，它在我常用的函数头中正常工作，如下所示：

/**
 * @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

所以这个文档的标题应该是这样的：

/**
 * @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

@复制：JSDoc doesn't display a table of arguments and return value/name/description

遇到同样的问题！

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 会生成函数描述。

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