使用jsdoc来logging匿名对象和函数的最佳方式

编辑：这在技术上是一个2部分的问题。 我已经select了涵盖这个问题的一般答案，并将其与处理具体问题的答案联系起来。

用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() 。 但是我想能够定义对象和function是什么。

我可以逃脱创buildPageRequest对象来logging：

 /** * @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 }; 

这很好（虽然我打开更好的方式来做到这一点）。

loggingcallback函数的最好方法是什么？ 我想让它在文档中知道，例如，callback函数的forms是：

 callback: function({PageResponse} pageResponse, {PageRequestStatus} pageRequestStatus) 

任何想法如何做到这一点？

Answer 1

您可以使用@name标记logging代码中不存在的内容：

  /** 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标签文档 。 您可能会发现名称path也很有用。

Answer 2

您可以使用@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) { ... } 

Answer 3

为了恭维studgeek的回答，我提供了一个例子，显示了使用Google Closure Compiler的JsDoc可以让你做什么。

请注意，logging的匿名types从生成的缩小文件中被移除，并且编译器确保有效的对象被传入（如果可能的话）。 但是，即使您不使用编译器，它也可以帮助下一个开发人员和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) { }; }; 

Answer 4

@link可以添加到方法和类的内联链接。

 /** * 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<br /> * function({@link PageResponse} pageResponse,{@link PageRequestStatus} pageRequestStatus) */ this.getPage = function (pageRequest, callback) { }; 

不理想，但它完成了工作。

Answer 5

Google Closure Compiler Annotations为此提供了typesexpression式 ，其中包括指定特定参数的types，返回types，甚至是这种types的expression式 。 许多图书馆都在关注Google Closure Compiler Annotations，因为他们想用它来缩小他们的代码。 所以它有一些动力。 缺点是我没有看到说明的方法。

为了提供描述，可能JSDoc工具包参数与属性方法将工作（看看页面的底部）。 这就是我现在正在做的。 JSDoc工具包正准备开始使用V3，所以反馈可能会很好。

Answer 6

您可以使用@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 }; 

如果您正在使用某种构build系统，则可以轻松地从构build中省略虚拟方法。