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

Question

// 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)
}

score 533 · Accepted Answer

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

score 291 · Accepted Answer

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

score 145 · Accepted Answer

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

score 21 · Accepted Answer

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

score 14 · Accepted Answer

パラメータに特定のプロパティがあると予想される場合は、追加の@paramタグを指定してそのプロパティを文書化できます。たとえば、employee パラメータに名前と部門のプロパティが必要な場合は、次のように文書化できます。

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

score 0 · Accepted Answer

これらのケース用の新しい@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
 */

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

6 に答える 6

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

Related

Reference