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

How to document returned data in JsDoc

本文关键字：返回 数据 记录 JsDoc      更新时间：2023-09-26

如何记录向服务器请求返回的JSON结果?

例子
/**
 * Gets a user's data
 * @returns {jQuery}
 */
function getUserData(userId){
   return $.get('/usr/' + userId);
}
在上面的示例中，返回的数据将是JSON对象，例如 
{
   "name" : "Bob",
   "status" : 2
}

/**
 * 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，它甚至不是Object。

引用JQuery的类型文档:

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

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

在这个例子中，我使用的是promise和handler。我从处理程序中创建了一个函数，这样可以更清楚地记录它，但这通常是通过匿名函数完成的。

我还将$.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)，如果你能收集到多行默认设置/初始化并将其放在类中，这就是我建议的方式。

相关文章：