我的大多数Javascript函数都相对简单，并因其副作用而被调用：我使用jQuery来操作DOM或进行Ajax调用。我更喜欢以"揭示模块模式"的风格编写函数。
我刚刚发现JSDoc注释Javascript文件有一个好处：在注释的帮助下，Eclipse的JS开发工具可以解析我的JS文件并填充Eclipse大纲视图(否则将为空)。
现在我想知道注释的要点是什么，或者说是好的做法是什么？我不习惯。
谷歌JS风格指南介绍了一些关于JSDoc的内容：建议只使用可用标签的子集，以及其他建议。
目前，我提出了模板(此代码没有任何有用的作用)：
/**
* @fileOverview Say something meaningful about the js file.
* @author <a href="mailto:my@email.net">My name</a>
* @version 1.0.1
*/
/**
* @namespace What the namespace contains or which apps/webpages use it
*/
if (!window['my']['namespace']) {
window['my']['namespace'] = {};
my.namespace = (function() {
/**
* Documentation string...
* @memberOf window.my.namespace
* @private
*/
var clear = function(){};
/**
* Documentation string...
* @memberOf window.my.namespace
* @public
*/
function delete_success(data){
var str = "# of files affected: " + data.length;
$('<pre id="success"/>').html(str).appendTo('#del_0b');
$('<pre id="success"/>').html(data.result).appendTo('#del_sf');
}
//more code
return {
"method1": method1,
"delete_success" : delete_success
};
})(); //my.namespace
} //end if
我应该在这里使用JSDoc标记@function或@memberOf，还是两者都使用？@field标签怎么样？return子句是否也应该是JSDoc的？使用哪些标签？我真的应该不使用@public标签吗？我觉得这里很有用。
有什么建议吗？有人知道一个好的，实用的JSDoc风格的小项目指南吗？
如果您正在寻找代码示例，我发现找到它们的最佳位置是在jsdoc用户Google Group的档案中。我在那里的运气比搜索谷歌要好得多，如果你问一个问题，他们通常都很乐意帮忙。
我不能说Eclipse支持，但有一个新版本的jsdoc，jsdoc3。查看此处的文档。这有点不完整，但我知道他们已经编写了更新并准备好进行审查，所以他们应该很快就会改进。
关于@function和@memberof的具体问题，您可能希望使用@function，而不是@memberof进行简单的功能文档。
在Eclipse中，@memberOf(大写O)为大纲(Ctrl+O快捷键)执行技巧。我主要将JSDoc用于Eclipse大纲，但也将@author用于人类：)
我还在私有函数上使用@private。
IMHO JSDT还可以，但没有太大帮助，它最近没有太多发展。您应该使用Eclipse JSHint插件或将TypeScript与Eclipse插件一起使用(您可以进行重构，但会增加一些复杂性)。
对于我(Eclipse 4.3开普勒)来说，以下操作很好：
my.namespace.foo.AbstractClass = {
/** @memberOf my.namespace.foo.StaticClass <- this statement already
* fixes the Eclipse Outline and Package Views for all other members
*/
staticMethod1 : function() { /* ... */ },
/** no need to add some JSDoc here for the Outline etc. */
staticMethod2 : function() { /* ... */ }
}
(对于"非抽象"类，说Java，应该类似)
这很好，因为：
- 不重复命名空间或JSDoc标记几乎是最低限度的
- 我不必摆弄
prototype或this - 立即创建"抽象类">1
1:我知道-一切都是对象-但我觉得有了更强的类型和名称空间环境/更清晰/更定义的概念(如Java)会更好。整个JavaScript的东西刚刚发展起来，(IMHO)非常糟糕，很难在更大的环境中使用，有多个程序员和坚实的重构支持，良好的可维护性、可测试性、模块化、依赖性管理、自我文档等。