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？

P.S。如果有一个“你做错了”的类型答案并没有直接回答问题，而是建议一种完全避免问题的方法，我很乐意听到它;我当然不是JSDoc专家。

Answer 1

你的同事不是严格正确的。

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

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

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

从对象的角度来看，每当你以一种非显而易见的方式将一个Function对象分配给一个对象成员时，你都想做同样的事情（通过非显而易见的＆＃39;，我的意思是静态分析的术语，即如果你不使用函数表达式。）

所以，像

var ageGetter = function() {
    console.log("A lady never tells");
}

var Person = {

  name: "Gertrude", 

  getAge: ageGetter

  getName: function() {
    return this.name;
  }
}

要求@method明确使用@function或getAge，getName明确使用{。}}。

最后一点：你不需要明确地包含@method名称，除非这也不可能推断（在这一点上，你可能正在进行一些非常时髦的实例化，所以可能是避难所＆＃ 39;无论如何都能够依靠自动文档生成。）

Answer 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;

有没有办法避免使用JSDoc“@method”注释

2 个答案: