关于使用 jsDoc 记录嵌套数组和对象数据的问题答案

【问题标题】：Questions about documenting nested array and object data with jsDoc关于使用 jsDoc 记录嵌套数组和对象数据的问题
【发布时间】：2012-08-10 16:35:25
【问题描述】：

如何使用 jsdoc 格式化嵌套数组和对象？

这是我的最佳猜测：

an_obj = { 
        username1 : [
            {
                param1 : "value 1-1-1",
                param2 : "value 1-1-2",
                optional_nested : "1-1--2"
            },
            {
                param1 : "value 1-2-1",
                param2 : "value 1-2-2"
            },
        ],
        username2 : [
            {
                param1 : "value 2-1-1",
                param2 : "value 2-1-2"
            },
            {
                param1 : "value 2-2-1",
                param2 : "value 2-2-2",
                optional_nested : "2-2--2"              

            }
        ]
    }
}


/**
 * A function description.
 * @param {Object} obj
 * @param {Object} obj.username  This is not the object name, but a name type. 
 * @param {Array}  obj.username.array Desc...  using [] would conflict with optional params.
 *                                    However this could be confused with an object called array.
 * @param {String} obj.username.array.param1 Desc... This is the object name rather than a type.
 * @param {String} obj.username.array.param2 Desc... 
 * @param {String} obj.username.array.[optional_param] Desc... 
 */
var myFunc = function(obj){
    //...
};
myFunc(an_obj);

如何指示一个对象是由某种字符串索引的？

如何定义嵌套数组？

也不确定在可选参数中放置方括号的位置。

【问题讨论】：

标签： javascript jsdoc

【解决方案1】：

你可以尝试这样做：（这里指定http://code.google.com/p/jsdoc-toolkit/wiki/TagParam）

/**
* @param {String[]} obj.username.array
*/

这应该将obj.username.array 声明为一个字符串数组。你用的是jsdoc还是jsdoc3？

【讨论】：

我目前正在使用 jsdoc-toolkit v3。我不知道如何处理这样的事情 {id: 'moo', items: [{url: '...',description: 'moo2'},...]}
这无济于事，案例是记录匿名对象数组，而不是真实对象数组

【解决方案2】：

我建议检查this。我可能会这样写：

//{Object{username:<Array<Object{param1:String, param2:String,[optional_nest]:string}>>}}

【讨论】：

链接已失效，上面的示例使用 jsdoc 3.3 抛出“无效类型表达式”