Question

我的大多数Javascript函数都相对简单，并且需要它们的副作用：我使用jQuery来操作DOM或进行Ajax调用。我更喜欢以“揭示模块模式”的方式编写我的函数。

I just discovered JSDoc-注释Javascript文件有一个好处：在annotations的帮助下，Eclipse的JS开发工具可以解析我的JS文件和fill the Eclipse Outline View（否则会空）。

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

谷歌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？有哪些标签？我真的不应该使用@public标签吗？我觉得这很有用。

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

Answer 1

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

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

关于您关于@function和@memberof的具体问题，您可能希望使用@function，而不是@memberof来获取简单的功能文档。

Answer 2

在Eclipse中@memberOf（使用大写字母O）可以完成大纲（ Ctrl + O 快捷方式）。我主要使用JSDoc作为Eclipse大纲，但我也使用@author作为人类：）

我还在私有函数上使用@private。

恕我直言JSDT可以，但不是很有帮助，最近并没有发展很多。您应该使用Eclipse JSHint插件或将TypeScript与Eclipse插件一起使用（您可以进行重构但会增加一些复杂性）。

Answer 3

对我来说（Eclipse 4.3 Kepler）以下工作正常：

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() { /* ... */ }
}

（对于＆＃34;非抽象＆＃34;类，说 Java ，它应该类似）

这很好，因为：

几乎不需要重复命名空间或JSDoc标记
我不必吝啬prototype或this
＆＃34;抽象类＆＃34; ¹立即创建

^1：我知道 - 一切都是对象 - 但我更喜欢更强大的类型和命名空间环境/更清晰/更定义的概念，比如Java。整个JavaScript的东西刚刚成长，（恕我直言）非常糟糕，难以在具有多个程序员和强大的重构支持，良好的可维护性，可测试性，模块化，依赖管理，自我文档等的更大环境中工作。

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

3 个答案: