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

问题描述

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

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

记录 callback 函数的最佳方式是什么?我想在文档中说明一下，比如回调函数的形式是:

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屋！