// 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)
}
从@param页面：
如果预期参数具有特定的属性，您可以在该参数的@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后面，但它似乎已被弃用（示例在此）。
/**
* @param {{a: number, b: string, c}} myObj description
*/
@returns。/**
* @param {Object} myObj description
* @param {number} myObj.a description
* @param {string} myObj.b description
* @param {} myObj.c description
*/
@returns。@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
*/
@returns。https://jsdoc.app/tags-type.html
提示：
要记录一个可选值，您可以使用[]：
/**
* @param {number} [opt_number] this number is optional
*/
或者：
/**
* @param {number|undefined} opt_number this number is optional
*/
{{dir: A|B|C }}？ - CMCDragonkai{[myVariable]: string}。 - FrondorFunction returns object where keys are dynamically generated. Example: {1: 'Pete', 2: 'Mary', 3: 'John'}. Usually, we iterate over this object with the help of for(var key in obj){...}.
Possible JSDoc according to 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
}
Function returns object where keys are known constants. Example: {id: 1, title: 'Hello world', type: 'LEARN', children: {...}}. We can easily access properties of this object: object.id.
Possible JSDoc according to https://groups.google.com/forum/#!topic/jsdoc-users/TMvUedK9tC4
Fake It.
/**
* 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
}
}
The Full Monty.
/**
@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);
}
Define a type.
/**
@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
}
}
According to https://google.github.io/styleguide/javascriptguide.xml#JsTypes
The record type.
/**
* @return {{myNum: number, myObject}}
* An anonymous type with the given type members.
*/
function getTmpObject() {
return {
myNum: 2,
myObject: 0 || undefined || {}
}
}
对于@return标记，请使用{{field1: Number, field2: String}}，请参见：http://wiki.servoy.com/display/public/DOCS/Annotating+JavaScript+using+JSDoc
如果期望一个参数具有特定的属性，您可以通过提供额外的@param标签来记录该属性。例如，如果预期一个名为employee的参数具有名称和部门属性，则可以按以下方式进行记录：
如果期望一个参数具有特定的属性，您可以通过提供额外的@param标签来记录该属性。例如，如果预期一个名为employee的参数具有名称和部门属性，则可以按以下方式进行记录：
/**
* 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
对于这些情况，现在有一个新的@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
*/