13

我个人不是生成文档的忠实粉丝（我更像是一个“阅读源卢克”的人），但我可以看到这些文档对其他人有何用处。现在，通常他们生成文档不会影响我，除了一件事：@method。

大多数 JSDoc 注释（例如@param）对于阅读源代码的人仍然非常有用，但@method100% 是多余的：

/*
 * @param num number to add five to
 * @method addFive
 */
function addFive(num) { ...

所以，我真的很想避免数百@method行代码把我们的代码弄得乱七八糟。但是，我的同事认为@methodJSDoc 生成器（他正在使用 YUI 生成器）必须能够生成类的方法列表。

所以，我的问题（对那里的 JSDoc 专家）是：有没有办法生成有用的文档（即使用列出的类的方法）@method？或者，如果@method确实需要，是否有任何 JSDoc 生成器可以从函数名中推断出方法名，这样我就可以@method不用了@method addFive？

PS如果有一个“你做错了”类型的答案，它没有直接回答问题，但提出了一种完全避免问题的方法，我很想听听；我当然不是 JSDoc 专家。

4

2 回答 2

14

您的同事并不完全正确。

这@method是一个JSDoc3扩展，是 的同义词@function，在此处定义。

正如那些文档概述的那样，您只需要使用@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;
  }
}

需要明确使用@methodor @function，getAge但不需要 for getName。

Final point: you do not need to explicitly include the @method name unless that, too, is impossible to infer (at which point, you're probably doing some pretty funky instantiation, so probably haven't been able to rely on auto doc-generation much anyway).

于 2012-08-03T16:33:14.547 回答
3

我在这里可能是错的，但由于在 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;
于 2012-07-28T20:10:32.260 回答