我正在为浏览器应用程序在工作中编写自己的图书馆,并且我有同样的旧问题决定如何评论代码.
我试图遵循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.
