如何在JsDoc中记录返回的数据

/**
 * 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);

正如Felix指出的那样，返回值不是JSON，甚至不是对象。

引用JQuery的类型文档：

从jQuery 1.5开始，$ .ajax（）方法返回jqXHR对象，该对象是XMLHTTPRequest对象的超集。有关更多信息，请参见$ .ajax条目的jqXHR部分。

由于$.get和$.getJSON都是的简写$.ajax，因此同样适用。

在示例中，我使用了promise和一个处理程序。我已经从处理程序中创建了一个函数，因此可以对其进行更清晰的记录，但这通常是使用匿名函数来完成的。

我还转换$.get为$.getJSON，它将JSON.parse为您进行调用（将回复从字符串转换为对象）。$.get的处理程序将@param {string}改为使用。

更新资料

OP在一条评论中询问如何使用自定义数据处理此问题，以便将来的开发人员知道通话中会发生什么。

现在我们已经有了数据，让我们来看一下记录数据。

根据复杂性和是否需要初始化，有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)如果您可以收集多行默认设置/初始化并将其放在类中，则建议这样做。