Как документировать возвращенные данные в 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, метод $ .ajax() возвращает объект jqXHR, который является подмножеством объекта XMLHTTPRequest. Для получения дополнительной информации смотрите раздел jqXHR в $ .ajax записи

С $.get и $.getJSON оба Shorthands для $.ajax, то же самое.

В примере я использую обещание и обработчик. Я сделал функцию из обработчика, чтобы ее можно было документировать более четко, но это часто делается с анонимной функцией.

Я также преобразовал $.get в $.getJSON, который сделает вызов JSON.parse для вас (который преобразует ответ от строки в объект). Обработчик $.get возьмет вместо этого @param {string}.

Update

В замечании ОП вопрос, как справиться с этим с помощью пользовательских данных, так что будущее DEV будет знать, что ожидать в вызове.

Теперь, когда у нас есть данные, давайте рассмотрим его документирование.

Существует 3 эффективных решения для документации, в зависимости от сложности, и если у вас есть инициализация.

Простейшим было бы создание @typedef с использованием @property для описания свойств, это не требует дополнительного кода и является чисто документацией.

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), если вы можете собрать более нескольких строк настройки/инициализации по умолчанию и поместить его в класс, так я предлагаю идти.