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

编辑:从技术上讲这是一个两部分的问题。我选择了涵盖一般问题并与处理特定问题的答案相关联的最佳答案。

用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)

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

最佳答案

您可以使用@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也很有用。

关于javascript - 用jsdoc记录匿名对象和函数的最佳方法，我们在Stack Overflow上找到一个类似的问题：https://stackoverflow.com/questions/3171454/