如何在JavaScript中记录返回 [英] How to document return in JavaScript

问题描述

我正在为浏览器应用程序的工作编写自己的库，我遇到了同样的问题，决定如何评论代码。

I'm writing my own library for the project at work for a browser application and I am having the same old problem deciding how to comment the code.

I我试图遵循 JsDoc 语法，但可能会继续 Google Closure Compiler 方式。我可能最终在文档中使用了两个@return和@returns标签，只是为了便携（当我设置文档的自动生成时）。

I'm trying to follow the JsDoc syntax, but will probably continue the Google Closure Compiler way. I may end up using two @return and @returns tags in the documentation, just for portability sake (when I setup the auto-generation of the documentation).

现在，问题，如何记录函数中自定义匿名对象的返回？例如：

return {
    username: 'username',
    password: 'password',
    enabled:  true
};

JsDoc有一个示例，说明如何记录@param以期望具有某些字段的对象，但不是@returns标签。同样，记录类型的Google Closure Compiler文档也很模糊，没有任何示例可以解决。

JsDoc has an example of how a @param can be documented to expect object with certain fields, but not the @returns tag. Similarly, the Google Closure Compiler documentation of a Record Type is vague and has no example to work it out.

推荐答案

关闭 - 编译器使用 JSDoc注释的一个子集（并添加了一些自己的注释）。有关完整集，请参阅编译器的注释参考。 JSDoc注释类似于JavaDoc注释，是一个以 / ** （两颗星）开头的注释块。虽然评论的每一行通常以它自己的 * 开头，但这是一种不需要的约定。每行只允许一个JSDoc标记，但标记的参数可以跨越多行。

The Closure-compiler uses a subset of the JSDoc annotations (and adds a few of its own). See the annotation reference for the compiler for the complete set. A JSDoc annotation is similar to a JavaDoc annotation and is a comment block that begins with /** (two stars). While each line of the comment often begins with it's own *, that is a convention that is not required. Only one JSDoc tag is allowed per line, but the arguments for a tag can span multiple lines.

注释通常适用于以下语句。以下是一些示例：

The annotation typically applies to the following statement. Here are some examples:

/** @type {string} */ var a;

类型演员

Type Cast

var b = /** @type {string} */ (window['foo']);

注意额外的括号

/**
 * @param {string} bar
 * @return {boolean}
 */
function foo(bar) { return true; }

函数表达式

Function Expressions

/** @type {function(string):boolean} */
var foo = function(bar) { return true; }

var foo2 =
  /**
   * @param {string} bar
   * @return {boolean}
   */
  function(bar) { return true; }

Typedef

复杂类型（包括为了方便和可维护性，可以使用typedef对别名和记录类型进行别名。这些注释可能很长，但可以拆分多行以便于阅读。

Typedef

Complex types (including unions, and record types) can be aliased for convenience and maintainability using a typedef. These annotations can be long, but can be split over multiple lines for readability.

/** @typedef {{
 *             foo:string,
 *             bar:number,
 *             foobar:number|string
 *           }}
 */
var mytype;

对于您的原始示例，有几种可能的方法来注释这样的函数返回值。其中一个最具体但仍然方便的是记录类型：

For your original example, there are several possible ways to annotate such a function return value. One of the most specific and still convenient is the record type:

/** @return {{username:string, password:string, enabled:boolean}} */
function() {
  return {
    username: 'username',
    password: 'password',
    enabled:  true
  }
}

注意额外的 {} 。另外请记住，记录类型不会阻止属性重命名。

Note the extra {}. Also keep in mind that record types will not prevent property renaming.

此注释告诉编译器该函数返回一个带有 username ，密码和已启用属性。其他有效选项是在其他地方定义接口，并将返回值强制转换为该接口。最不具体的注释是 Object 或 * 。

This annotation tells the compiler that the function returns an anonymous type with username, password and enabled properties. Other valid options would be to define an interface elsewhere and typecast the return value to be that interface. The least specific annotation would be Object or *.

要查看各种可能的注释，请查看编译器项目中的extern文件。

To see a wide range of possible annotations, take a look at the extern files in the Compiler project.

这篇关于如何在JavaScript中记录返回的文章就介绍到这了，希望我们推荐的答案对大家有所帮助，也希望大家多多支持IT屋！