有没有什么办法可以避免使用JSDoc“@method”注释

我不是个人生成文档的大粉丝（我更像是一个“读卢克源”的人），但我可以看到这种文件可能对其他人有用。现在，通常他们的文档生成不会影响我，除了一件事情：@method。有没有什么办法可以避免使用JSDoc“@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专家。

来源

2012-07-26 machineghost

JSDoc 3，对吧？ – Dancrumb 2012-08-03 16:23:31

你的同事并不严格正确。

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

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

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

从实物的角度来看，你会想要做同样的，只要你在一个非显而易见的方式分配函数对象的对象成员（由“非显而易见性” ，我的意思是根据静态分析，即如果你不使用函数表达式）。

所以，像

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这个名字，除非这也不可能推断出来（在这一点上，你可能做了一些非常有趣的实例化，所以可能无法依靠无论如何，对于自动文档生成）。

来源

2012-08-03 16:33:14 Dancrumb

我可能在这里是错的，但由于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-28 20:10:32

有没有什么办法可以避免使用JSDoc“@method”注释

回答

相关问题