使用jsdoc记录匿名对象和函数的最佳方法

Question

编辑:这在技术上是一个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)

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

Answer 1

您可以使用@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标签文档.您可能会发现名称路径也很有用.

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.

请注意,已记录的匿名类型将从生成的缩小文件中删除,编译器会确保传入有效对象(如果可能).但是,即使您不使用编译器,它也可以帮助下一个开发人员和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

希望我在这个话题上还不算太晚，但你可以做这样的事情

/**
  * Get a page from the server
  * @param {PageRequest} pageRequest
  * @param {(pageResponse: PageResponse, pageRequestStatus: PageRequestStatus) => void} callback
  */
this.getPage = function(pageRequest, callback) {}

这种方法的缺点是您无法记录每个参数的作用。