Question

我是JSDoc和类似Javadoc的惯例的绝对新手;我正在寻找一些悬而未决的水果来起床和跑步，而且我很短暂。

我的代码是这样组织的，主要是个人风格：

var app = app || {};

app.ui = {
  someUIfunction: function() {},
  someUIparams: {},
  anotherFunction: function(string, object) {}
}

app.rest = {
  someRESTCall: function(url,data) {},
  someRESTparams: {},
  moreRESTCall: function(url,data) {}
}

理论上，一切都可能只是“app”下的一个整体对象，但我喜欢分别拆分下一级对象，以便在IDE中进行方便的冷折叠和搜索。另外，这对我来说只是感觉很整洁。

我无法做的是深入了解第三级功能和对象。 JSDoc3似乎不想为我呈现它;而且，我不喜欢有一个只是“app”的起始页面（或者我最后给应用程序提供的任何东西）作为命名空间......我希望它的成员也在索引中。这是我的尝试（原谅愚蠢的例子！）：

/**
 * Application Namespace for this marvellous application
 * 
 * @namespace app
 */
var app = app || {};

/**
 * An object containing methods and parameters used for UI presentation logic
 * 
 * @type {object}
 * @memberOf app
 * @property {string} title - a string used as the title of the UI
 * @property {function} init - a function to initialize the UI
 */
app.ui = {
  // not bothering to document this for whatever reason
  title: "some title",
  /**
   * @memberOf app.ui
   * @params {object} params - an object containing necessary initialization parameters
   */
  init: function(params) {
    // some initialization logic
  }
}

有两个问题：

理想情况下，我希望app.ui拥有自己的页面。 @namespace是正确的方法吗？它有效，但在视觉上它在索引中伪装成与app本身处于同一级别。
app.ui.init根本没有记录。

在我看来（并且不可否认，这可能只是无知！）如果我使用JSDoc3会更高兴：

app.ui.init = function() {} // (etc)

但就我而言，这将是相当丑陋的。我需要用来指示嵌套成员的语法的任何指针都是我所追求的。

JSDoc3 - 整洁的对象文字组织

0 个答案: