使用jsdoc记录匿名对象和函数的最佳方式 [英] Best way to document anonymous objects and functions with jsdoc

问题描述

编辑：这在技术上是一个2部分的问题。我选择了一般的问题的最佳答案，并与处理具体问题的答案相联系。

This is technically a 2 part question. I've chosen the best answer that covers the question in general and linked to the answer that handles the specific question.

记录匿名对象和功能的最佳方法是什么与jsdoc？

What is the best way to document anonymous objects and functions with 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（）。但是我希望能够定义对象和函数是什么。

Neither the PageRequest object or the callback exist in code. They will be provided to getPage() at runtime. But I would like to be able to define what the object and function are.

我可以通过创建 PageRequest 对象来记录：

I can get away with creating the PageRequest object to document that:

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

这很好（尽管我有更好的方式来做到这一点）。

And that's fine (though I'm open to better ways to do this).

记录回调函数的最好方法是什么？我想在文档中知道，例如，回调函数的形式是：

What is the best way to document the callback function? I want to make it know in the document that, for example, the callback function is in the form of:

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

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

Any ideas how to do this?

推荐答案

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

You can document stuff that doesnt exist in the code by using the @name tag:

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

Here is the @name tag documentation . You might find name paths useful too.

这篇关于使用jsdoc记录匿名对象和函数的最佳方式的文章就介绍到这了，希望我们推荐的答案对大家有所帮助，也希望大家多多支持IT屋！