我个人不是生成文档的忠实拥护者(我更像是一个“阅读源代码 Luke”的人),但我可以看到此类文档对其他人有何用处。现在,通常他们生成的文档不会影响我,除了一件事:@method。
大多数 JSDoc 注释(例如 @param
)对于阅读源代码的人来说仍然非常有用,但是 @method
是 100% 冗余的:
/*
* @param num number to add five to
* @method addFive
*/
function addFive(num) { ...
所以,我真的很想避免让数百行 @method
弄乱我们的代码。但是,我的同事认为 @method
是 JSDoc 生成器(他使用的是 YUI 生成器)能够生成类的方法列表所必需的。
所以,我的问题(对那里的 JSDoc 专家)是:有没有什么方法可以在没有 @method
的情况下生成有用的文档(即,使用列出的类的方法)?或者,如果确实需要 @method
,是否有任何 JSDoc 生成器可以从函数名称中推断出方法名称,这样我就可以使用 @method
而不是 @method addFive
?
附言如果有一个“你做错了”类型的答案没有直接回答问题,而是提出了一种完全避免问题的方法,我很想听听;我当然不是 JSDoc 专家。
最佳答案
您的同事并不完全正确。
@method
是一个 JSDoc3 @function
的同义词扩展名,即 defined here .
如这些文档所述,您只需要使用 @function
来强制 JSDoc 将变量识别为函数。这方面的一个例子是:
/**
* @function
*/
var func = functionGenerator.generate();
从对象的 Angular 来看,每当您以非显而易见的方式将 Function 对象分配给对象成员时,您都希望执行相同的操作(“非显而易见”,我指的是静态分析,即如果你没有使用函数表达式)。
所以,像
var ageGetter = function() {
console.log("A lady never tells");
}
var Person = {
name: "Gertrude",
getAge: ageGetter
getName: function() {
return this.name;
}
}
getAge
需要显式使用 @method
或 @function
,getName
则不需要。
最后一点:您不需要显式包含 @method
名称,除非它也无法推断(此时,您可能正在做一些非常时髦的实例化,所以可能无论如何都不能太依赖自动文档生成)。
关于javascript - 有什么方法可以避免使用 JSDoc "@method"注释,我们在Stack Overflow上找到一个类似的问题: https://stackoverflow.com/questions/11675065/