如何在jsdoc中描述“对象”参数？

// My function does X and Y. // @params {object} parameters An object containing the parameters // @params {function} callback The callback function function(parameters, callback) { } 

但是，如何描述参数对象的结构？ 例如，它应该是这样的：

 { setting1 : 123, // (required, integer) setting2 : 'asdf' // (optional, string) } 

Answer 1

从@param维基页面 ：

---

参数与属性

如果一个参数预期有一个特定的属性，你可以立即在该参数的@param标签之后logging该参数，如下所示：

  /** * @param userInfo Information about the user. * @param userInfo.name The name of the user. * @param userInfo.email The email of the user. */ function logIn(userInfo) { doLogIn(userInfo.name, userInfo.email); } 

---

曾经有一个@config标签紧跟在相应的@param之后，但似乎已经被废弃（ 例子在这里 ）。

Answer 2

我发现已经有了关于@return标签的答案，但是我想给出更多的细节。

首先，官方的JSDoc 3文档没有给出任何有关自定义对象的@return的例子。 请参阅http://usejsdoc.org/tags-returns.html 。 现在，让我们看看我们能做些什么，直到出现一些标准。

• 函数返回dynamic生成密钥的对象。 例如： {1: 'Pete', 2: 'Mary', 3: 'John'} 。 通常，我们在for(var key in obj){...}的帮助下迭代这个对象。

  可能的JSDoc根据https://google.github.io/styleguide/javascriptguide.xml#JsTypes

   /** * @return {Object.<number, string>} */ function getTmpObject() { var result = {} for (var i = 10; i >= 0; i--) { result[i * 3] = 'someValue' + i; } return result } 

• 函数返回键是已知常量的对象。 例如： {id: 1, title: 'Hello world', type: 'LEARN', children: {...}} 。 我们可以很容易地访问这个对象的属性： object.id 。

  根据https://groups.google.com/forum/#!topic/jsdoc-users/TMvUedK9tC4可能的JSDoc

  • 假装。

     /** * Generate a point. * * @returns {Object} point - The point generated by the factory. * @returns {number} point.x - The x coordinate. * @returns {number} point.y - The y coordinate. */ var pointFactory = function (x, y) { return { x:x, y:y } } 

  • 光猪六壮士。

     /** @class generatedPoint @private @type {Object} @property {number} x The x coordinate. @property {number} y The y coordinate. */ function generatedPoint(x, y) { return { x:x, y:y }; } /** * Generate a point. * * @returns {generatedPoint} The point generated by the factory. */ var pointFactory = function (x, y) { return new generatedPoint(x, y); } 

  • 定义一个types。

     /** @typedef generatedPoint @type {Object} @property {number} x The x coordinate. @property {number} y The y coordinate. */ /** * Generate a point. * * @returns {generatedPoint} The point generated by the factory. */ var pointFactory = function (x, y) { return { x:x, y:y } } 

  根据https://google.github.io/styleguide/javascriptguide.xml#JsTypes

  • loggingtypes。

     /** * @return {{myNum: number, myObject}} * An anonymous type with the given type members. */ function getTmpObject() { return { myNum: 2, myObject: 0 || undefined || {} } } 

Answer 3

现在有四种不同的方式来将对象logging为参数/types。 每个都有自己的用途。 但是，其中只有3个可以用来logging返回值。

对于具有一组已知属性的对象（变体A）

 /** * @param {{a: number, b: string, c}} myObj description */ 

此语法对于仅用作此函数的参数的对象是理想的，并且不需要每个属性的进一步描述。 它也可以用于@returns 。

对于具有一组已知属性的对象（变体B）

非常有用的是带有属性语法的参数 ：

 /** * @param {Object} myObj description * @param {number} myObj.a description * @param {string} myObj.b description * @param {} myObj.c description */ 

此语法对于仅用作此函数参数的对象是理想的，并且需要对每个属性进行进一步的描述。 这不能用于@returns 。

对于将在源中的多个点使用的对象

在这种情况下， @typedef非常方便。 您可以在源代码中的某一时刻定义types，并将其用作@param或@returns或其他可以使用types的JSDoc标签的types。

 /** * @typedef {Object} Person * @property {string} name how the person is called * @property {number} age how many years the person lived */ 

然后你可以在@param标签中使用它：

 /** * @param {Person} p - Description of p */ 

对于其值都是相同types的对象

 /** * @param {Object.<string, number>} dict */ 

第一种types（string）logging了JavaScript中的键总是一个string，或者至less总是被强制转换为一个string。 第二种types（数字）是值的types; 这可以是任何types。 这个语法也可以用于@returns 。

资源

有关loggingtypes的有用信息可以在这里find：

http://usejsdoc.org/tags-type.html

PS：

要logging一个可以使用[]的可选值：

 /** * @param {number} [opt_number] this number is optional */ 

要么：

 /** * @param {number|undefined} opt_number this number is optional */ 

Answer 4

对于@return标记，请使用{{field1: Number, field2: String}} ，请参阅： http : //wiki.servoy.com/display/public/DOCS/Annotating+JavaScript+using+JSDoc

Answer 5

这些情况下有一个新的@config标记。 他们链接到前面的@ @param 。

 /** My function does X and Y. @params {object} parameters An object containing the parameters @config {integer} setting1 A required setting. @config {string} [setting2] An optional setting. @params {MyClass~FuncCallback} callback The callback function */ function(parameters, callback) { // ... }; /** * This callback is displayed as part of the MyClass class. * @callback MyClass~FuncCallback * @param {number} responseCode * @param {string} responseMessage */