jsdocで「オブジェクト」引数を記述する方法は？

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

しかし、parametersオブジェクトの構造をどのように説明すればよいですか？たとえば、次のようになります。

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

@param Wikiページ：

プロパティを持つパラメータ

パラメータに特定のプロパティがあることが予想される場合は、そのパラメータの@paramタグの直後に次のようにドキュメント化できます。

 /**
  * @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);
 }

以前は対応する@paramの直後に続く@configタグがありましたが、廃止されたようです（ここの例）。

現在、オブジェクトをパラメータ/タイプとして文書化する方法は4つあります。それぞれに独自の用途があります。ただし、戻り値のドキュメント化に使用できるのは3つだけです。

プロパティの既知のセットを持つオブジェクト（バリアント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が非常に便利です。ソースのある時点でタイプを定義し、それをタイプとして@param、@returnsまたはタイプを使用できる他のJSDocタグとして使用できます。

/**
 * @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
 */

または@returns：

/**
 * @returns {Person} Description
 */

値がすべて同じタイプのオブジェクトの場合

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

最初のタイプ（文字列）は、JavaScriptで常に文字列であるか、少なくとも常に文字列に強制変換されるキーのタイプを文書化します。2番目のタイプ（数値）は値のタイプです。これはどのタイプでもかまいません。この構文は@returns、同様に使用できます。

資源

ドキュメントタイプに関する有用な情報は、次の場所にあります。

https://jsdoc.app/tags-type.html

PS：

使用できるオプションの値を文書化するには[]：

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

または：

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

@returnタグについてはすでに回答があるようですが、詳しく説明したいと思います。

まず第一に、公式のJSDoc 3ドキュメントでは、カスタムオブジェクトの@returnの例を示していません。https://jsdoc.app/tags-returns.htmlを参照してください。さて、標準が現れるまで何ができるか見てみましょう。

• 関数は、キーが動的に生成されるオブジェクトを返します。例：{1: 'Pete', 2: 'Mary', 3: 'John'}。通常、を使用してこのオブジェクトを反復処理しますfor(var key in obj){...}。

  https://google.github.io/styleguide/javascriptguide.xml#JsTypesに従って可能なJSDoc

  /**
   * @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);
    }

  • タイプを定義します。

    /**
     @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によると

  • レコードタイプ。

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

@returnタグの使用については{{field1: Number, field2: String}}、http：//wiki.servoy.com/display/public/DOCS/Annotating+JavaScript+using+JSDocを参照してください。

パラメータが特定のプロパティを持つことが予想される場合、追加の@paramタグを提供することにより、そのプロパティを文書化できます。たとえば、従業員パラメータに名前と部門のプロパティが必要な場合は、次のようにドキュメント化できます。

/**
 * Assign the project to a list of employees.
 * @param {Object[]} employees - The employees who are responsible for the project.
 * @param {string} employees[].name - The name of an employee.
 * @param {string} employees[].department - The employee's department.
 */
function(employees) {
    // ...
}

明示的な名前なしでパラメーターが分解される場合、オブジェクトに適切な名前を付け、そのプロパティを文書化できます。

/**
 * Assign the project to an employee.
 * @param {Object} employee - The employee who is responsible for the project.
 * @param {string} employee.name - The name of the employee.
 * @param {string} employee.department - The employee's department.
 */
Project.prototype.assign = function({ name, department }) {
    // ...
};

出典：JSDoc

@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
 */