6

私の VS2015 JavaScript アプリには、JSDoc@typedefコメントを使用して文書化した REST API から取得した JSON オブジェクトがあります。

/**
 * @typedef {Object} JSON_Response
 * @property {Number} id
 * @property {String} name
 * @property {JSON_Response_Tag} tag
 */

/**
 * @typedef {Object} JSON_Response_Tag
 * @property {Number} id
 * @property {String} color
 */

これらの JSON オブジェクトを使用するメソッドの JSDoc コメントでこの型を参照すると、Intellisense ドキュメントを問題なく取得できます。

/**
 * @param {JSON_Response} response
 */
function process_response(response) {
  // process response here...
}

ただし、これを配列で機能させることはできません-配列にインデックスを付けようとすると、VSがIntellisenseコンテキストを取得できないときに発生する「黄色の三角形」メニューが表示されます。

/**
 * @typedef {Object} JSON_Response
 * @property {Number} id
 * @property {String} name
 * @property {JSON_Response_Tag[]} tags
 */

/**
 * @param {JSON_Response} response
 */
function process_response(response) {
  response.tags[0]. // no intellisense here
}

JSDoc の他の推奨方法である を使用する{Array.<JSON_Response>}と、VS にresponse配列であることを通知しますが、その下にあるものには Intellisense を提供しません。Microsoft 独自の XML コメントはこの機能を提供しますが、関数パラメーターに対してのみです。関数が呼び出されるたびにこのドキュメントを追加する必要があるため、オブジェクト内に到達することはできません。

JavaScript の VS Intellisense で、基になる型を使用して配列を文書化する方法はありますか?

コードを書かなければならない場合、副作用を最小限に抑えたい/リリースから除外できるようにしたい.

4

2 に答える 2

1

直感に反するように思えますが、XML コメントの制限や JSDoc を解析する Intellisense の限られた機能に煩わされるよりも、JSON 型に関するドキュメントを取得する最善の方法は、型を生成するコンストラクターを実際に記述し、それを参照して、文書化の目的でのみ解析されます。

つまり、JavaScript に次のようなコンストラクターを含めます。

/**
 * @constructor {Object} JSON_Response
 * @property {Number} id
 * @property {String} name
 * @property {JSON_Response_Tag[]} tags
 */
function JSON_Response(){
  return {
    id: 0,
    name: "",
    tags: [new JSON_Reponse_Tag()]
  }
}

/**
 * @constructor {Object} JSON_Response_Tag
 * @property {Number} id
 * @property {String} color
 */
function JSON_Response_Tag(){
  return {
    id: 0,
    color: "#000000"
  }
}

定義された個々のオブジェクト タイプのすべてが必ずしも必要というわけではありません。好きなものを使用できます。JSON 出力のサンプルをコピーして貼り付けることもできます。内部オブジェクトを他の変数に格納する場合にのみ、クラスを分割する必要があります。

次に、実際に JavaScript ファイルをページに含める代わりに、これらすべての JSON コンストラクターを別のファイルに入れ、XML 参照ディレクティブを入れることができます。

/// <reference path="~/path/to/schema_file.js" />

消費する JavaScript ファイルの先頭に - Visual Studio は、ドキュメントを提供するという唯一の目的でコードを実行します。

于 2016-01-19T16:49:50.187 に答える