我的大部分
Javascript功能都比较简单,并且要求它们的sideeffects：我使用jQuery来操纵DOM或进行Ajax调用.我更喜欢在“显示模块模式”的风格中写我的功能.
我的just discovered JSDoc-注释Javascript文件有一个好处：借助于annotations,Eclipse的JS开发工具可以解析我的JS文件和fill the Eclipse Outline View(否则为空).
现在我想知道什么是细点,还是注释的良好做法？我不习惯
google JS style指南介绍了有关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标签怎么样？
返回条款是否应该被JSDoc’mented？用哪个标签？
我真的不会使用@public标签吗？我觉得在这里很有用
任何建议？
有没有人知道一个好的,实用的JSDoc风格指南小项目？
解决方法
如果您正在寻找代码示例,我发现找到它们的最佳位置在
jsdoc-users Google Group的档案中.我比Google搜索更好运气,如果您提出问题,他们通常会很好的帮助.
我不能说Eclipse的支持,但是有一个新版本的jsdoc,jsdoc3.检查文档here.它有点不完整,但我知道他们有更新写入并准备审查,所以他们应该尽快改善.
关于你关于@function和@memberof的具体问题,你可能想使用@function,而不是@memberof用于简单的函数文档.