How to describe "object" arguments in jsdoc?
From the @param wiki page:
Parameters With Properties
If a parameter is expected to have a particular property, you can document that immediately after the @param tag for that parameter, like so:
/**
* @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);
}
There used to be a @config tag which immediately followed the corresponding @param, but it appears to have been deprecated (example here).
I see that there is already an answer about the @return tag, but I want to give more details about it.
First of all, the official JSDoc 3 documentation doesn't give us any examples about the @return for a custom object. Please see https://jsdoc.app/tags-returns.html. Now, let's see what we can do until some standard will appear.
Function returns object where keys are dynamically generated. Example:
{1: 'Pete', 2: 'Mary', 3: 'John'}
. Usually, we iterate over this object with the help offor(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 || {} } }
By now there are 4 different ways to document objects as parameters/types. Each has its own uses. Only 3 of them can be used to document return values, though.
For objects with a known set of properties (Variant A)
/**
* @param {{a: number, b: string, c}} myObj description
*/
This syntax is ideal for objects that are used only as parameters for this function and don't require further description of each property.
It can be used for @returns
as well.
For objects with a known set of properties (Variant B)
Very useful is the parameters with properties syntax:
/**
* @param {Object} myObj description
* @param {number} myObj.a description
* @param {string} myObj.b description
* @param {} myObj.c description
*/
This syntax is ideal for objects that are used only as parameters for this function and that require further description of each property.
This can not be used for @returns
.
For objects that will be used at more than one point in source
In this case a @typedef comes in very handy. You can define the type at one point in your source and use it as a type for @param
or @returns
or other JSDoc tags that can make use of a type.
/**
* @typedef {Object} Person
* @property {string} name how the person is called
* @property {number} age how many years the person lived
*/
You can then use this in a @param
tag:
/**
* @param {Person} p - Description of p
*/
Or in a @returns
:
/**
* @returns {Person} Description
*/
For objects whose values are all the same type
/**
* @param {Object.<string, number>} dict
*/
The first type (string) documents the type of the keys which in JavaScript is always a string or at least will always be coerced to a string. The second type (number) is the type of the value; this can be any type.
This syntax can be used for @returns
as well.
Resources
Useful information about documenting types can be found here:
https://jsdoc.app/tags-type.html
PS:
to document an optional value you can use []
:
/**
* @param {number} [opt_number] this number is optional
*/
or:
/**
* @param {number|undefined} opt_number this number is optional
*/