使用jsdoc记录匿名对象和函数的最佳方式
使用jsdoc记录匿名对象和函数的最佳方式
提问于 2010-07-03 20:18:23
编辑:从技术上讲，这是一个分为两部分的问题。我已经选择了涵盖一般问题的最佳答案，并链接到处理特定问题的答案。
用jsdoc记录匿名对象和函数的最佳方式是什么？
/**
* @class {Page} Page Class specification
*/
var Page = function() {
/**
* Get a page from the server
* @param {PageRequest} pageRequest Info on the page you want to request
* @param {function} callback Function executed when page is retrieved
*/
this.getPage = function(pageRequest, callback) {
};
};代码中既不存在PageRequest对象也不存在callback。它们将在运行时提供给getPage()。但我希望能够定义对象和函数是什么。
我可以创建PageRequest对象来记录这一点：
/**
* @namespace {PageRequest} Object specification
* @property {String} pageId ID of the page you want.
* @property {String} pageName Name of the page you want.
*/
var PageRequest = {
pageId : null,
pageName : null
};这很好(尽管我对更好的方法持开放态度)。
记录callback函数的最佳方式是什么？我想在文档中让它知道，例如，回调函数的形式为：
callback: function({PageResponse} pageResponse, {PageRequestStatus} pageRequestStatus)你知道该怎么做吗？
回答 6
Stack Overflow用户
回答已采纳
发布于 2010-08-23 04:44:00
您可以使用@name标记来记录代码中不存在的内容。
/**
* Description of the function
* @name IDontReallyExist
* @function
* @param {String} someParameter Description
*/
/**
* The CallAgain method calls the provided function twice
* @param {IDontReallyExist} func The function to call twice
*/
exports.CallAgain = function(func) { func(); func(); }这是@name tag documentation。您可能会发现name paths也很有用。
Stack Overflow用户
发布于 2013-07-23 21:10:48
您可以使用@callback或@typedef。
/**
* @callback arrayCallback
* @param {object} element - Value of array element
* @param {number} index - Index of array element
* @param {Array} array - Array itself
*/
/**
* @param {arrayCallback} callback - function applied against elements
* @return {Array} with elements transformed by callback
*/
Array.prototype.map = function(callback) { ... }Stack Overflow用户
发布于 2013-04-19 00:51:37
为了对studgeek的回答表示赞赏，我提供了一个示例来说明JsDoc with Google Closure Compiler允许您做什么。
请注意，文档中的匿名类型会从生成的精简文件中删除，编译器会确保传入有效的对象(如果可能)。但是，即使您不使用编译器，它也可以帮助下一位开发人员和WebStorm (IntelliJ)等工具理解它，并为您提供代码完成功能。
// This defines an named type that you don't need much besides its name in the code
// Look at the definition of Page#getPage which illustrates defining a type inline
/** @typedef { pageId : string, pageName : string, contents: string} */
var PageResponse;
/**
* @class {Page} Page Class specification
*/
var Page = function() {
/**
* Get a page from the server
* @param {PageRequest} pageRequest Info on the page you want to request
*
* The type for the second parameter for the function below is defined inline
*
* @param {function(PageResponse, {statusCode: number, statusMsg: string})} callback
* Function executed when page is retrieved
*/
this.getPage = function(pageRequest, callback) {
};
};页面原文内容由Stack Overflow提供。腾讯云小微IT领域专用引擎提供翻译支持
原文链接：
https://stackoverflow.com/questions/3171454
复制相关文章
相似问题