如何记录方法的“对象”参数答案

【问题标题】：How to document an "object" parameter of a method如何记录方法的“对象”参数
【发布时间】：2013-03-02 01:30:18
【问题描述】：

我正在尝试为使用 YUIDoc 的 JavaScript 方法编写一些文档。它看起来像：

/** 
    Returns an instance of className

    @method getInstance
    @param {string} className the of the class used to create the instance
    @param {Object} options these are options used to create the instance
**/
function getInstance(className, options) { ..... }

现在，options 对象可以有多个参数，例如options.id、options.single 等。

如何将此信息添加到此@param 的文档中？

【问题讨论】：

Google Closure Compiler 会将其标记为 {{id:string,single:whatever}} 或 {Object.} 如果它是通用字典，但我不知道是否这是常见的语法或它的扩展。见本页底部：developers.google.com/closure/compiler/docs/js-for-compiler

标签： javascript documentation yuidoc

【解决方案1】：

来自参考：http://yui.github.com/yuidoc/syntax/index.html

“如示例所示，您还可以嵌套@param 标签。这使您能够记录具有自己特定嵌套结构的对象参数。”

@param {Object} [options] Data 
  to be mixed into the event 
  facade of the `change` 
  event(s) for these attributes.
  @param {Boolean} [options.silent]
    If `true`, no `change` event 
    will be fired.

【讨论】：

【解决方案2】：

在撰写本文时的当前版本 YUIDOC 0.3.45 中，为了描述方法接收的对象，您应该首先声明对象（options，在下面的示例中）和然后是带有点符号的属性（例如，options.url）。

/**
 * Describe your method
 *
 * @method yourMethodName
 * @param {object} options - These are the options you may pass
 * @param {string} options.url - the url
 * @param {string} options.otherOption - description of other option
 */

【讨论】：

有没有办法像这样表示所需的属性？在参数下方添加@required 不起作用。