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

Question

编辑:从技术上讲，这是一个由两部分组成的问题。我选择了涵盖一般问题的最佳答案，并链接到处理特定问题的答案。

使用 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 对象或回调 均不存在于代码中。它们将在运行时提供给 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 tag documentation .你可能会发现 name paths也很有用。