JSDoc:オブジェクト構造を返す


144

返されるオブジェクトの構造をJSDocに通知するにはどうすればよいですか。私は@return {{field1: type, field2: type, ...}} description構文を見つけて試しました:

/**
 * Returns a coordinate from a given mouse or touch event
 * @param  {TouchEvent|MouseEvent|jQuery.Event} e    
 *         A valid mouse or touch event or a jQuery event wrapping such an
 *         event. 
 * @param  {string} [type="page"]
 *         A string representing the type of location that should be
 *         returned. Can be either "page", "client" or "screen".
 * @return {{x: Number, y: Number}} 
 *         The location of the event
 */
var getEventLocation = function(e, type) {
    ...

    return {x: xLocation, y: yLocation};
}

これは正常に解析されますが、結果のドキュメントには単に次のように記載されています。

Returns: 
    The location of an event
    Type: Object

私はAPIを開発していますが、返されるオブジェクトについて知ってもらう必要があります。これはJSDocで可能ですか?JSDoc3.3.0-beta1を使用しています。


私はそれ@typedefが回避策/解決策であることを知っていますが、これがリテラルオブジェクトで機能しないのは奇妙なようです。誰かが将来これに遭遇した場合(私がしたように)、問題を追加しました、このページよりも多くの情報を持つ可能性の github.com/jsdoc/jsdoc/issues/1678を。
Leszek

回答:


263

@typdefを使用して構造を個別に定義する

/**
 * @typedef {Object} Point
 * @property {number} x - The X Coordinate
 * @property {number} y - The Y Coordinate
 */

そして、それを戻り値の型として使用します。

/**
 * Returns a coordinate from a given mouse or touch event
 * @param  {TouchEvent|MouseEvent|jQuery.Event} e    
 *         A valid mouse or touch event or a jQuery event wrapping such an
 *         event. 
 * @param  {string} [type="page"]
 *         A string representing the type of location that should be
 *         returned. Can be either "page", "client" or "screen".
 * @return {Point} 
 *         The location of the event
 */
var getEventLocation = function(e, type) {
    ...

    return {x: xLocation, y: yLocation};
}

2
ありがとう。複数の@returnステートメントは、実際に作業を行うが、彼らはいくつかのリターン(一つの箇条書きの状態であるかのように、彼らは出力にリストされていますpoint - Objectし、他の2つの箇条書きのためにpoint.x - Numberpoint.y - Number)。私はそれに耐えることができますが、返されたオブジェクトの出力を圧縮する方法はないと思いますか?または非常に少なくとも、のエントリを持っているpoint.xpoint.yインデント?
BlackWolf、2015

1
はい、それは最良の選択肢のようです。名前のないリターンエンティティを作成する方法があるのではないかと思いましたが@typedef、ドキュメントの出力という点では、このアプローチが最も明確です。
BlackWolf、2015

groovy、2番目のオプションが単に最良であるため、最初のオプションを削除。
BGerrissen、2015

1
@inner定義を追加するか、タイプ定義を行うとglobal、ドキュメントにスコープが設定されます。+1
OnurYıldırım

1
私はいつも使ってきました@typedef {Object} Point。実際、この2行のフォームを使用するPointと、PhpStormで「未解決の変数またはタイプポイント」というメッセージが表示されます。@typedefドキュメントは、これをサポートしていますが、それが有効な変種だ場合、私はこの答えを編集する必要はありません。
David Harkness

22

すでに投稿されている提案の代わりに、次の形式を使用できます。

/**
 * Get the connection state.
 *
 * @returns {Object} connection The connection state.
 * @returns {boolean} connection.isConnected Whether the authenticated user is currently connected.
 * @returns {boolean} connection.isPending Whether the authenticated user's connection is currently pending.
 * @returns {Object} connection.error The error object if an error occurred.
 * @returns {string} connection.error.message The error message.
 * @returns {string} connection.error.stack The stack trace of the error.
 */
getConnection () {
  return {
    isConnected: true,
    isPending: false,
    error
  }
}

これにより、次のドキュメント出力が提供されます。

    Get the connection state.

    getConnection(): Object

    Returns
    Object: connection The connection state.
    boolean: connection.isConnected Whether the authenticated user is currently connected.
    boolean: connection.isPending Whether the authenticated users connection is currently pending.
    Object: connection.error The error object if an error occurred.
    string: connection.error.message The error message.
    string: connection.error.stack The stack trace of the error.

17

クリーンなソリューションは、クラスを作成してそれを返すことです。

/** 
 *  @class Point
 *  @type {Object}
 *  @property {number} x The X-coordinate.
 *  @property {number} y The Y-coordinate.
 */
function Point(x, y) {
  return {
        x: x,
        y: y
    };
}

/**
 * @returns {Point} The location of the event.
 */
var getEventLocation = function(e, type) {
    ...
    return new Point(x, y);
};

これを実行してもGoogle Closure Compilerを使用すると、「コンストラクターをインスタンス化できません」という警告が表示されます。(@returnの上にある)関数に@constructorを追加しようとしましたが、役に立ちませんでした。誰かがそれを修正する方法を知っている場合は、私に知らせてください。ありがとう!
AndroidDev 2017年

2
@AndroidDevこれは、関数Pointがコンストラクタではないためです。関数の本体を次のものに置き換えるために変更しPointますthis.x = x; this.y = y;
Feirell

1
ここでnewを使用する必要がある理由がわかりません。なぜPoint(x、y)を返さないのですか?
CHANist

@CHANist、new構文はからインスタンスを作成することconstructorです。がなければnew、のコンテキストはthisグローバルコンテキストになります。せずにインスタンスを作成してみることができますnew効果を確認に。
Akash
弊社のサイトを使用することにより、あなたは弊社のクッキーポリシーおよびプライバシーポリシーを読み、理解したものとみなされます。
Licensed under cc by-sa 3.0 with attribution required.