// My function does X and Y.
// @params {object} parameters An object containing the parameters
// @params {function} callback The callback function
function(parameters, callback) {
}
但是如何描述参数对象的结构?例如,它应该类似于:
{
setting1 : 123, // (required, integer)
setting2 : 'asdf' // (optional, string)
}
#1 楼
在@param Wiki页面上:带属性的参数
如果期望参数具有特定的属性,则可以在@param之后立即记录该参数的标记,如下所示:
/**
* @param userInfo Information about the user.
* @param userInfo.name The name of the user.
* @param userInfo.email The email of the user.
*/
function logIn(userInfo) {
doLogIn(userInfo.name, userInfo.email);
}
以前有一个@config标记,紧随其后的是@param,但它似乎具有不推荐使用(此处为示例)。
#2 楼
到目前为止,有4种不同的方式将对象记录为参数/类型。每个都有自己的用途。但是,只能使用它们中的3个来记录返回值。对于具有一组已知属性的对象(变体A)
/**
* @param {{a: number, b: string, c}} myObj description
*/
此语法非常适合仅用作该函数参数的对象,不需要进一步描述每个属性。
它也可以用于
@returns
。对于对象具有一组已知属性(变式B)
具有属性语法的参数非常有用:
/**
* @param {Object} myObj description
* @param {number} myObj.a description
* @param {string} myObj.b description
* @param {} myObj.c description
*/
此语法非常适合对象只能用作此函数的参数,并且需要每个属性的进一步说明。
不能用于
@returns
。对于将在一个以上点使用的对象source
在这种情况下,@typedef非常方便。您可以在源代码中的一点上定义类型,并将其用作
@param
或@returns
或其他可以使用类型的JSDoc标签的类型。/**
* @typedef {Object} Person
* @property {string} name how the person is called
* @property {number} age how many years the person lived
*/
然后可以在
@param
标签中使用此标签:/**
* @param {Person} p - Description of p
*/
,或者在
@returns
中使用:/**
* @returns {Person} Description
*/
值均相同的对象
/**
* @param {Object.<string, number>} dict
*/
第一个类型(字符串)记录了键的类型,这些键的类型在JavaScript中始终为字符串,或者至少始终为强制为字符串。第二种类型(数字)是值的类型;
该语法也可以用于
@returns
。资源
有关文档类型的有用信息可以在这里找到:
https://jsdoc.app/tags-type.html
PS:
要记录可选值,可以使用
[]
:/**
* @param {number} [opt_number] this number is optional
*/
或:
/**
* @param {number|undefined} opt_number this number is optional
*/
评论
变量1是否可以与多种类型的属性一起使用?像{{dir:A | B | C}}一样?
– CMCDragonkai
17年6月16日在14:00
这里可以有任何类型的注释,所以是的
–西蒙·齐克斯(Simon Zyx)
17年7月25日在16:31
对于动态生成键的对象?像{[myVariable]:string}
– Frondor
19年1月10日在14:55
vscode(下面的1.51)不能很好地处理@typedef,它不能显示提示的对象属性,到目前为止,我坚持使用param {Object}
–秋浪
20 Dec 5'3:51
#3 楼
我看到已经有一个有关@return标记的答案,但是我想提供更多有关它的详细信息。首先,官方JSDoc 3文档没有提供任何有关@return标记的示例。 @return为自定义对象。请参阅https://jsdoc.app/tags-returns.html。现在,让我们看看在出现某种标准之前我们可以做些什么。
函数返回动态生成键的对象。例如:
{1: 'Pete', 2: 'Mary', 3: 'John'}
。通常,我们会在for(var key in obj){...}
的帮助下对这个对象进行迭代。可能的JSDoc根据https://google.github.io/styleguide/javascriptguide.xml#JsTypes
/**
* @return {Object.<number, string>}
*/
function getTmpObject() {
var result = {}
for (var i = 10; i >= 0; i--) {
result[i * 3] = 'someValue' + i;
}
return result
}
函数返回键为已知常量的对象。例如:
{id: 1, title: 'Hello world', type: 'LEARN', children: {...}}
。我们可以轻松访问此对象的属性:object.id
。可能的JSDoc根据https://groups.google.com/forum/#!topic/jsdoc-users/TMvUedK9tC4
将其伪装。
/**
* Generate a point.
*
* @returns {Object} point - The point generated by the factory.
* @returns {number} point.x - The x coordinate.
* @returns {number} point.y - The y coordinate.
*/
var pointFactory = function (x, y) {
return {
x:x,
y:y
}
}
蒙蒂。
/**
@class generatedPoint
@private
@type {Object}
@property {number} x The x coordinate.
@property {number} y The y coordinate.
*/
function generatedPoint(x, y) {
return {
x:x,
y:y
};
}
/**
* Generate a point.
*
* @returns {generatedPoint} The point generated by the factory.
*/
var pointFactory = function (x, y) {
return new generatedPoint(x, y);
}
定义类型。
/**
@typedef generatedPoint
@type {Object}
@property {number} x The x coordinate.
@property {number} y The y coordinate.
*/
/**
* Generate a point.
*
* @returns {generatedPoint} The point generated by the factory.
*/
var pointFactory = function (x, y) {
return {
x:x,
y:y
}
}
根据https://google.github.io/styleguide/javascriptguide。 xml#JsTypes
记录类型。
/**
* @return {{myNum: number, myObject}}
* An anonymous type with the given type members.
*/
function getTmpObject() {
return {
myNum: 2,
myObject: 0 || undefined || {}
}
}
#4 楼
对于@return
标签,请使用{{field1: Number, field2: String}}
,请参见:http://wiki.servoy.com/display/public/DOCS/Annotating+JavaScript+using+JSDoc 评论
原始链接没有任何有用的地方。我相信它的新版本在这里:wiki.servoy.com/display/Serv7/Annotating+JavaScript+Using+JSDoc
–约翰·克鲁(John Krull)
15年1月8日在20:52
#5 楼
如果期望参数具有特定的属性,则可以通过提供其他@param标记来记录该属性。例如,如果期望员工参数具有名称和部门属性,则可以将其记录如下:
/**
* Assign the project to a list of employees.
* @param {Object[]} employees - The employees who are responsible for the project.
* @param {string} employees[].name - The name of an employee.
* @param {string} employees[].department - The employee's department.
*/
function(employees) {
// ...
}
参数经过分解而没有显式名称,可以为对象指定一个适当的名称并记录其属性。
/**
* Assign the project to an employee.
* @param {Object} employee - The employee who is responsible for the project.
* @param {string} employee.name - The name of the employee.
* @param {string} employee.department - The employee's department.
*/
Project.prototype.assign = function({ name, department }) {
// ...
};
源:JSDoc
#6 楼
这些情况下有一个新的@config
标签。它们链接到前面的@param
。/** My function does X and Y.
@params {object} parameters An object containing the parameters
@config {integer} setting1 A required setting.
@config {string} [setting2] An optional setting.
@params {MyClass~FuncCallback} callback The callback function
*/
function(parameters, callback) {
// ...
};
/**
* This callback is displayed as part of the MyClass class.
* @callback MyClass~FuncCallback
* @param {number} responseCode
* @param {string} responseMessage
*/
评论
您可以指向@config标记的文档吗?我在usejsdoc.org上找不到任何内容,并且此页面表明@config已过时。
– Dan Dascalescu
15年7月30日在8:25
我认为此时不建议使用@config。 YUIDoc建议改为使用@attribute。
–迈克·德西蒙(Mike DeSimone)
15年7月30日在14:08
评论
不幸的是,returns标签似乎没有等效的代码。google.com/ p / jsdoc-toolkit / wiki / TagReturns
– Michael Bylstra
2012年11月11日在2:50
在这个类似的答案stackoverflow.com/a/14820610/3094399中,他们还在开头添加了@param {Object}选项。猜猜它可能是多余的。
– pcatre
15年1月23日在15:30
任何想法如何记录一个对象成员这是选项?我的意思是我的用户对象应该具有用户名,并且可以具有全名。所以我如何指定全名是可选的
– Yash Kumar Verma
20年4月13日在9:25