如何在JavaScript中返回文档

我正在为浏览器应用程序在工作中编写自己的图书馆,并且我有同样的旧问题决定如何评论代码.

我试图遵循JsDoc语法,但可能会继续Google Closure Compiler的方式.我可能最终在文档中使用两个@return和@returns标签,仅用于可移植性(当我设置文档的自动生成时).

现在,问题是,你如何记录一个自定义匿名对象从一个函数返回？例如：

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

JsDoc有一个例子,说明如何使用@param来记录某些字段的对象,而不是@returns标签.类似地,记录类型的Google Closure Compiler文档是模糊的,没有任何示例可以使用.

解决方法

Closure编译器使用 JSDoc annotations的子集(并添加了它自己的一些).查看 annotation reference for the compiler的整套. JSDoc注释类似于JavaDoc注释,是以/ **(两颗星)开头的注释块.虽然注释的每一行通常以自己的*开头,但这是不需要的约定.每行只允许一个JSDoc标签,但标签的参数可以跨多行.

注释通常适用于以下语句.这里有些例子：

变量

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

输入Cast

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

注意额外的括号

命名功能

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

函数表达式

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

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

的typedef

可以使用typedef为复杂类型(包括联合和记录类型)进行别名,以方便和维护.这些注释可能很长,但可以分割多行以便可读性.

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

对于您的原始示例,有几种可能的方法来注释这样的函数返回值.记录类型中最具体和最方便的一个：

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

注意额外的{}.还要记住,记录类型不会阻止属性重命名.

该注释告诉编译器该函数返回匿名类型,其用户名,密码和已启用的属性.其他有效的选项将是在其他地方定义一个接口,并将返回值打包为该接口.最不具体的注释将是Object或*.

要查看各种可能的注释,请查看extern files in the Compiler project.

如何在JavaScript中返回文档

解决方法

猜你在找的JavaScript相关文章