JsDocで返されたデータを文書化する方法

Question

返されたJSON結果をサーバーに文書化するにはどうすればよいですか？

例

/** 
* Gets a user's data 
* @returns {jQuery} 
*/ 
function getUserData(userId){ 
    return $.get('/usr/' + userId); 
} 

上記の例では、返されたデータは、フェリックスが指摘するように、戻り値がJSONないよう

{ 
    "name" : "Bob", 
    "status" : 2 
} 

Answer 1

/** 
* Gets a user's data request 
* @return {jQuery.jqXHR} 
*/ 
function getUserData(userId){ 
    return $.getJSON('/usr/' + userId); 
} 

/* 
* Handles the result of a user data request. 
* @param {Object} data The JSON object, already converted to an Object. 
*/ 
function doSomethingWithUserData(data) { 
    console.log('do something with user data:', data); 
} 

getUserData(userId).done(handleUserData); 

としてJSONの対象となり、それはですオブジェクトでさえない。

引用JQuery's types documentation：jQueryの1.5のよう

、$アヤックス（）メソッドは、XMLHTTPRequestオブジェクトのスーパーセットであるjqXHRオブジェクトを返します。 $.getと$.getJSONが$.ajaxのために、両方の略記法であるため、詳細については、$アヤックスエントリ

のjqXHRセクションを参照してください、同じことが当てはまります。

私はpromiseとハンドラを使用しています。私はハンドラから関数を作りましたので、より明確に文書化することができましたが、これはしばしば無名関数で行われます。

$.getを$.getJSONに変換しました。が呼び出されます（文字列の返信がオブジェクトに変換されます）。 $.getのハンドラは代わりに@param {string}になります。コメントのOPで

アップデートは、将来DEVが呼び出しに期待するものを知っているように、カスタムデータでこれをどのように処理するかを尋ねました。

データを取得しましたので、これを文書化してみましょう。

複雑さや初期化を行う場合は、3つの良い解決策があります。

@propertyを使って@typedefを作成してプロパティを記述するのが最も簡単ですが、これは追加のコードを必要とせず、純粋にドキュメントです。使用中の

goog.provide('UserData'); 
/* 
* UserData (in the style of Closure's JSDocs) 
* @typedef {{ 
* name: {string}, 
* title: {string} 
* }} 
*/ 
UserData; 

または

/* 
* UserData (in the style of useJSDocs) 
* @typedef {Object} 
* @property {string} name 
* @property {string} title 
*/ 
var UserData; 

：

/* 
* Handles the result of a user data request. 
* @param {UserData} data The JSON object, already converted to an Object, 
* cast to UserData 
*/ 
function doSomethingWithUserData(data) { 
    console.log('do something with user data:', data); 
} 

と似ており、あなたにとってより有用である可能性が@interface @record。 最後に、あなたがlet user = new UserData(jsonUser)になっているまっすぐなクラスがあります。あなたがデフォルト設定/初期化を数行以上集めてクラスに入れることができれば、これは私が行くことを示唆しています。