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

Question

我不是个人生成文档的忠实粉丝(我更像是"读源Luke"有点人),但我可以看到这些文档对其他人有用.现在,通常他们生成的文档不会影响我,除了一件事:@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专家.

Answer 1

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

该@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;
  }
}

需要明确使用@method或@functionfor getAge,但不是getName.

最后一点:你不需要明确地包含@method名称,除非这也是不可能推断的(在这一点上,你可能正在进行一些非常时髦的实例化,所以可能还没有能够依赖于自动doc生成无论如何).