_Best实践JSDoc'ing以"揭示模块模式"风格编写的Javascript文件？

Question

我的大多数Javascript函数都相对简单,并且需要它们的副作用:我使用jQuery来操作DOM或进行Ajax调用.我更喜欢用"揭示模块模式"风格编写我的函数.

我刚刚发现 JSDoc-注释Javascript文件有一个好处:借助注释,Eclipse的JS开发工具可以解析我的JS文件并填充Eclipse Outline View(否则它将是空的).

现在我想知道注释的优点或优点是什么？我不习惯它.

谷歌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标签怎么样？返回子句是否也应该是JSDoc？有哪些标签？我真的不应该使用@public标签吗？我觉得这里很有用.

有什么建议？有没有人知道一个好的,实用的小型项目JSDoc风格指南？

Answer 1

如果您正在寻找代码示例，我发现找到它们的最佳位置是jsdoc-users Google Group的档案。我在那里的运气比搜索谷歌要好得多，如果你问问题，他们通常会很乐意提供帮助。

我不能谈论 Eclipse 支持，但是 jsdoc 有一个新版本，jsdoc3。查看此处的文档。它有点不完整，但我知道他们已经编写了更新并准备好进行审核，所以他们应该很快就会改进。

关于您关于@function和 的具体问题@memberof，您可能想要使用@function，而不是@memberof简单的函数文档。