有什么方法可以避免使用 JSDoc“@method”注解答案

【问题标题】：Is There Any Way to Avoid Using the JSDoc "@method" Annotation有什么方法可以避免使用 JSDoc“@method”注解
【发布时间】：2012-07-25 09:07:19
【问题描述】：

我个人不是生成文档的忠实拥护者（我更像是“阅读源卢克”的人），但我可以看到此类文档对其他人有何用处。现在，通常他们生成的文档不会影响我，除了一件事：@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 专家。

【问题讨论】：

标签： javascript jsdoc

【解决方案1】：

你的同事并不完全正确。

@method 是 JSDoc3 扩展名，是 @function 的同义词，即 defined here。

正如那些文档概述的那样，您只需要使用@function 来强制 JSDoc 将变量识别为函数。这方面的一个例子是：

/**
 * @function
 */
var func = functionGenerator.generate();

从对象的角度来看，每当您以非显而易见的方式将 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 名称，除非这也无法推断（此时，您可能正在做一些非常时髦的实例化，所以可能无法无论如何都要依赖自动文档生成）。

【讨论】：

【解决方案2】：

我在这里可能是错的，但由于在 JavaScript 中定义事物的方式有很多种，您需要@method 来进行某些定义。

// JSDoc will recognize this as an object member
var obj = {
    mymethod: function() {}
};

// There is no way for JSDoc to tell where my method is going to end up
var mymethod = function() {};
obj.mymethod = mymethod;

【讨论】：