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

Best way to document anonymous objects and functions with jsdoc

提问by Josh Johnson

Edit: 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.

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

What is the best way to document anonymous objects and functions with 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) {
    }; 
};

Neither the PageRequestobject or the callbackexist 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对象也不callback存在。它们将getPage()在运行时提供给。但我希望能够定义对象和功能是什么。

I can get away with creating the PageRequestobject to document that:

我可以通过创建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
};

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

这很好（尽管我愿意接受更好的方法来做到这一点）。

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

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

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

Any ideas how to do this?

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

采纳答案by Eric

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

您可以使用@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(); }

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

这是@name 标签文档。您可能会发现名称路径也很有用。

回答by kzh

You can use @callbackor @typedef.

您可以使用@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) { ... }

回答by Juan Mendes

To compliment studgeek's answer, I've provided an example that shows what JsDoc with Google Closure Compilerlets you do.

为了赞美struggeek 的回答，我提供了一个示例，展示了 带有Google Closure Compiler 的JsDoc可以让您做什么。

Note that the documented anonymous types get removed from the generated minified file and the compiler ensures valid objects are passed in (when possible). However, even if you don't use the compiler, it can help the next developer and tools like WebStorm (IntelliJ) understand it and give you code completion.

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

回答by Josh Johnson

@linkcan add inline links to methods and classes.

@link可以向方法和类添加内联链接。

/**
 * 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<br />
 * function({@link PageResponse} pageResponse,{@link PageRequestStatus} pageRequestStatus)
 */
this.getPage = function (pageRequest, callback) {
};

Not ideal, but it gets the job done.

不理想，但它完成了工作。

回答by studgeek

The Google Closure Compiler Annotations has Type Expressionsfor this which includes the ability to indicate type for specific arguments, return type, and even this. Many libraries are looking at following the Google Closure Compiler Annotations, because they want to use it to shrink their code. So it's got some momentum. The downside is I don't see a way to give the description.

Google Closure Compiler Annotations 具有用于此的类型表达式，其中包括指示特定参数的类型、返回类型甚至 this 的能力。许多库都在考虑遵循 Google Closure Compiler Annotations，因为他们想用它来缩小他们的代码。所以它有一些动力。缺点是我看不到给出描述的方法。

For providing the description perhaps the JSDoc Toolkit Parameters With Propertiesapproach would work (look at the bottom of the page). It's what I am doing right now. The JSDoc Toolkit is prepping to start work on V3, so feedback there might be good.

为了提供描述，JSDoc Toolkit Parameters With Properties方法可能会起作用（查看页面底部）。这就是我现在正在做的事情。JSDoc Toolkit 正在准备开始在 V3 上工作，所以那里的反馈可能很好。

回答by Dagg Nabbit

You could use @see to link to another method within the same class. The method would never be used, it would just be there for documentation purposes.

您可以使用 @see 链接到同一类中的另一个方法。该方法永远不会被使用，它只是用于文档目的。

/**
 * @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
     * @see #getPageCallback 
     */
    this.getPage = function (pageRequest, callback) {
    }; 

    /**
     * Called when page request completes 
     * @param {PageResponse} pageResponse The requested page
     * @param {PageRequestStatus} pageRequestStatus Status of the page
     */
    //#ifdef 0
    this.getPageCallback = function (pageResponse, pageRequestStatus) { };
    //#endif 
};

If you are using some kind of build system, the dummy method could easily be omitted from the build.

如果您使用某种构建系统，则可以轻松地从构建中省略 dummy 方法。