web-dev-qa-db-ja.com

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)
}
javascriptjsdoc
244
Andy Hin

@ 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タグがありましたが、廃止されたようです（ example here ）。

343
Jonny Buchanan

@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 || {}
    }
}
121
vogdb

現在、オブジェクトをパラメーター/タイプとして文書化する方法は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
 */
105
Simon Zyx

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

18
maliboo

これらの場合のための新しい@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
 */
2
Mike DeSimone