我已经开始为我的项目实现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}，我还有很多功能可以做到这一点，我只是想确保在清理所有文件中的所有函数之前我做对了。
我得到的错误是这样的：(尽管实际错误更详细一些(
srcFrameworkBusinessRulesRulescharacterGeneration.js in line 70 with tag title "param" and text "{[String]} inputData The list of allowable special characters that should be used srcFrameworkBusinessRulesRulescharacterGeneration.js in line 70 with tag title "param" and text "{[String]} inputMetaData Not used for this business rule.": Invalid type expression "[ srcFrameworkBusinessRulesRulescharacterGeneration.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标签的标头？
哇，好吧，我想我需要阅读更多关于文档的内容。总是一个好主意。大声笑
从 JSDoc 文档中复制粘贴： 链接： JSDoc @Name Tage 用法
@name标记强制 JSDoc 将 JSDoc 注释的其余部分与给定名称相关联，而忽略所有周围的代码。此标记最好用于代码中不容易看到的符号的"虚拟注释"，例如在运行时生成的方法。
使用 @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标记文档
因此，此文档的标题应如下所示：
/**
* @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
*/
有同样的问题！
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 将生成函数描述。
这个问题也可以通过定义函数并导出它们来解决。