web-dev-qa-db-ja.com

JSDocのドキュメントコレクション（型の配列）の戻り値とパラメーター

配列要素が次のいずれかになり得る場合にJSDocでArray戻り値（およびパラメーター）を文書化する方法：

  • タイプ（例：String、Array）。
  • オブジェクトリテラル。
javascriptjsdoc
26
Jonathan Chan

配列内のオブジェクトのタイプを文書化する方法を探している場合は、次のようなものが必要です。

 /**
  * @param {String[]} aliases
  */

http://code.google.com/p/jsdoc-toolkit/wiki/TagParam#Parameter_Type_Information

30
dmertl

与えられたscreeningsパラメータ：

screenings = [
    {
        timestamp: 1440157537,
        url: 'https://stackoverflow.com/a/22787287/1269037',
    },
    {
        timestamp: ...,
        url: ...,
    },
];

次の3つの方法のいずれかで文書化できます。

@typedef の使用：

/**
 * @typedef {Object} screening
 * @property {Number} timestamp - UNIX timestamp.
 * @property {String} url - Booking URL.
 */

/**
 * @param {screening[]}
 */
function positionTimes (screenings) {}

screeningオブジェクトのバリエーションを使用する関数が複数ある場合は、関数の名前空間を使用できます。

/**
 * @typedef {Object} positionTimes~screening
 * @property {Number} timestamp - UNIX timestamp.
 * @property {String} url - Booking URL.
 */

/**
 * @param {positionTimes~screening[]}
 */
function positionTimes (screenings) {}

/**
 * @typedef {Object} filterTimes~screening
 * @property {Number} timestamp - UNIX timestamp.
 * @property {String} url - Booking URL.
 */

/**
 * @param {filterTimes~screening[]}
 */
function filterTimes (screenings) {}

配列内の値の プロパティの文書化 ：

/**
 * @param {Object[]} screenings
 * @param {Number} screenings[].timestamp - Unix timestamp.
 * @param {String} screenings[].url - Booking URL.
 */
function positionTimes (screenings) {}

戻り値には名前がないため、これは @return された型の記述には機能しません。

コレクション定義の使用：

/**
 * @param {Array.<{timestamp: Number, url: String}>} screenings
 */
function positionTimes (screenings) {}

このアプローチの利点は、ワンライナーであるため、2番目の方法が機能しない@return宣言で使用できることです。

コレクション定義アプローチの欠点は、プロパティ値を記述できないことです。

14
Gajus

他のいくつかの回答で与えられたガイダンスがあなたのために働くことに気付くかもしれませんが、私はこの構文を好みます：

/**
 * @return {Array<String>} ...
 */

そして、他の人が提供したガイダンスと比較して、これはあなたがあなたの質問で与えた例に基づいてあなたの期待に近いと思います。

JSDocに関する優れた情報源は次のとおりです。 https://wiki.servoy.com/display/public/DOCS/JSDoc+Annotations

6
SirLenz0rlot

ドコによる @returns

/** 
 * @returns {Array} Lines from the file.
 */
function readLines(filepath) {
}

参照 。

3
Seyeong Jeong

のJSDocのドキュメントhttp://usejsdoc.org/タイプMyClassのメンバーを持つ配列の例があります。 2つの可能性があります。 1つは次のようになります。

@param{MyClass[]}

このような他のもの：

@param{Array.<MyClass>}

Arrayと.の間の<に注意してください。

0
Wilt