编辑:这在技术上是一个2部分问题。我选择了一般性问题的最佳答案,并与处理特定问题的答案相关联。
使用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)
任何想法如何做到这一点?
答案 0 :(得分:42)
您可以使用@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也很有用。
答案 1 :(得分:30)
您可以使用@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) { ... }
答案 2 :(得分:8)
为了赞美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) {
};
};
答案 3 :(得分:1)
答案 4 :(得分:1)
Google Closure编译器注释为此Type Expressions,其中包括指示特定参数,返回类型甚至此类型的类型的功能。许多图书馆都在关注Google Closure Compiler Annotations,因为他们希望使用它来缩小代码。所以它有一些动力。缺点是我没有看到给出描述的方法。
为了提供描述,也许JSDoc Toolkit Parameters With Properties方法可行(请查看页面底部)。这就是我现在正在做的事情。 JSDoc工具包正准备开始使用V3,因此反馈可能很好。
答案 5 :(得分:0)
您可以使用@see链接到同一个类中的另一个方法。永远不会使用该方法,它只是出于文档目的。
/**
* @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
* @see #getPageCallback
*/
this.getPage = function (pageRequest, callback) {
};
/**
* Called when page request completes
* @param {PageResponse} pageResponse The requested page
* @param {PageRequestStatus} pageRequestStatus Status of the page
*/
//#ifdef 0
this.getPageCallback = function (pageResponse, pageRequestStatus) { };
//#endif
};
如果您正在使用某种构建系统,则可以很容易地从构建中省略虚拟方法。