How to describe object arguments in jsdoc

Question

My function does X and Y      params  object  parameters An object containing the parameters     params  function  callback The callback function function parameters  callback        But how do I describe how the parameters object should be structured  For example it should be something like       setting1   123      required  integer    setting2    asdf      optional  string

User · Answer

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
 */

User · Answer

If a parameter is expected to have a specific property  you can document that property by providing an additional  param tag  For example  if an employee parameter is expected to have name and department properties  you can document it as follows           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                      If a parameter is destructured without an explicit name  you can give the object an appropriate one and document its properties           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                      Source  JSDoc

User · Answer

For  return tag use   field1  Number  field2  String    see  http   wiki servoy com display public DOCS Annotating JavaScript using JSDoc

User · Answer

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

User · Answer

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 of for var key in obj         Possible JSDoc according to https   google github io styleguide javascriptguide xml JsTypes          return  Object  lt number  string gt       function getTmpObject         var result          for  var i   10  i  gt   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

User · Answer

There s a new  config tag for these cases  They link to the preceding  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

[javascript] How to describe "object" arguments in jsdoc?

Examples related to javascript

Examples related to jsdoc