javascript - 有什么方法可以避免使用 JSDoc "@method"注释

Question

我个人不是生成文档的忠实拥护者(我更像是一个“阅读源代码 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 专家。

Answer 1

您的同事并不完全正确。

@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 名称，除非它也无法推断(此时，您可能正在做一些非常时髦的实例化，所以可能无论如何都不能太依赖自动文档生成)。