10

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

我刚刚发现JSDoc-注释 Javascript 文件有一个好处：在注释的帮助下，Eclipse 的 JS 开发工具可以解析我的 JS 文件并填充 Eclipse 大纲视图（否则它将是空的）。

现在我想知道注释的要点或良好做法是什么？我不习惯。

google JS style guide 说了一些关于 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'umented 吗？用哪些标签？我真的不应该使用@public 标签吗？我觉得这里很有用。

有什么建议吗？有谁知道小型项目的良好实用的 JSDoc 样式指南？

4

3 回答 3

3

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

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

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

于 2013-03-05T02:05:16.933 回答
0

对我来说（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() { /* ... */ }
}

（对于“非抽象”类，讲Java，应该是类似的）

这很好，因为：

  • 不重复命名空间或 JSDoc 标记几乎是最低要求
  • 我不必摆弄prototype或this
  • 立即创建“抽象类” 1

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

于 2016-02-29T14:18:22.397 回答
0

在 Eclipse （大写 O）中，大纲（ +快捷方式）@memberOf的诀窍。我主要将 JSDoc 用于 Eclipse 大纲，但我也 用于人类 :)CtrlO@author

我也用于@private私人功能。

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

于 2015-08-10T08:21:44.043 回答