How to describe “object” arguments in jsdoc? - GeeksforGeeks

19 Jul, 2019
There are various different ways to describe “object” parameters in JSDoc. We will look into 4 different ways, each with their own uses, in this article.
To document objects with specified properties:Syntax:/**
 * @param {{a: string, b: number}} Obj description
 */
This syntax is good practice for objects that will only be used as arguments for the given method without needing further documentation of each property. This can also be used for @returns.Example:<html>  <head>    <title>        GeeksforGeeks    </title></head>  <body>    <center>        <h1 style="color:green">          GeeksforGeeks      </h1>        <button onclick="Hello(a, b)">          Hello      </button>        <script>            /**             * @param {{a: string, b: number}} obj User information             */            function Hello(a, b) {                alert('User: ' + a + ', number:' + b);            };            var a = "Adarsh";            var b = 973;        </script>    </center></body>  </html>Output:Before:After:To document objects with specified properties (type 2):Syntax:/**
 * @param {Object} Obj  Description
 * @param {string} Obj.a  Description
 * @param {number} Obj.b  Description
 */
This syntax is good practice for objects that will only be used as arguments for the given method and need further documentation of each property. This cannot be used for @returns.Example:<html>  <head>    <title>        GeeksforGeeks    </title></head>  <body>    <center>        <h1 style="color:green">          GeeksforGeeks      </h1>        <button onclick="Hello(a, b)">          Hello      </button>        <script>            /**             * @param {Object} Obj  User information             * @param {string} Obj.a  name of user             * @param {number} Obj.b  number of user             */            function Hello(a, b) {                alert('User: ' + a + ', number:' + b);            };            var a = "name";            var b = 001;        </script>    </center></body>  </html>Output:Before:After:To document objects that will be used more than once in source:@typedef is useful in this situation. Once the type is defined in source, you can use it as a type for JSDoc tags like @param or @returns that make use of a type.Syntax:/**
 * @typedef {Object} Person
 * @property {number} age Length of time the person has lived
 * @property {string} name The word by which the person is addressed
 */
Can also be used in a @param tag:Syntax:/**
 * @param {Person} p - Description of p
 */
Can also be used in a @returns tag:Syntax:/**
 * @returns {Person} Description
 */
Example:<!DOCTYPE html><html>  <body>    <center>        <h1 style="color:green">          GeeksforGeeks      </h1>        <button onclick="Hello()">          Hello      </button>        <p id="demo"></p>          <script>           /**            * @typedef {Object} Person            * @property {number} age Length of time the person has lived            * @property {string} name The word by which the person is addressed            */           function Hello() {               document.getElementById(                 "demo").innerHTML = person.name + " " + person.age;           }           var person = {               name: "John",               lastName: "Doe",               age: 50,           };       </script>   </center>  </body>  </html>Output:Before:After:To document objects that have values of the same type:Syntax:/**
 * @param {Object.} Dict
 */
This syntax is good practice for objects whose values are all the same type. In this case, the first type i.e. string describes the type of JavaScript property (keys) that always remains of string type. The second type i.e. number describes the type of value, which can be of any type.This can also be used for @returns.
To document objects with specified properties:Syntax:/**
 * @param {{a: string, b: number}} Obj description
 */
This syntax is good practice for objects that will only be used as arguments for the given method without needing further documentation of each property. This can also be used for @returns.Example:<html>  <head>    <title>        GeeksforGeeks    </title></head>  <body>    <center>        <h1 style="color:green">          GeeksforGeeks      </h1>        <button onclick="Hello(a, b)">          Hello      </button>        <script>            /**             * @param {{a: string, b: number}} obj User information             */            function Hello(a, b) {                alert('User: ' + a + ', number:' + b);            };            var a = "Adarsh";            var b = 973;        </script>    </center></body>  </html>Output:Before:After:
Syntax:
/**
 * @param {{a: string, b: number}} Obj description
 */

This syntax is good practice for objects that will only be used as arguments for the given method without needing further documentation of each property. This can also be used for @returns.
Example:
<html>  <head>    <title>        GeeksforGeeks    </title></head>  <body>    <center>        <h1 style="color:green">          GeeksforGeeks      </h1>        <button onclick="Hello(a, b)">          Hello      </button>        <script>            /**             * @param {{a: string, b: number}} obj User information             */            function Hello(a, b) {                alert('User: ' + a + ', number:' + b);            };            var a = "Adarsh";            var b = 973;        </script>    </center></body>  </html>
Output:Before:After:
To document objects with specified properties (type 2):Syntax:/**
 * @param {Object} Obj  Description
 * @param {string} Obj.a  Description
 * @param {number} Obj.b  Description
 */
This syntax is good practice for objects that will only be used as arguments for the given method and need further documentation of each property. This cannot be used for @returns.Example:<html>  <head>    <title>        GeeksforGeeks    </title></head>  <body>    <center>        <h1 style="color:green">          GeeksforGeeks      </h1>        <button onclick="Hello(a, b)">          Hello      </button>        <script>            /**             * @param {Object} Obj  User information             * @param {string} Obj.a  name of user             * @param {number} Obj.b  number of user             */            function Hello(a, b) {                alert('User: ' + a + ', number:' + b);            };            var a = "name";            var b = 001;        </script>    </center></body>  </html>Output:Before:After:
Syntax:
/**
 * @param {Object} Obj  Description
 * @param {string} Obj.a  Description
 * @param {number} Obj.b  Description
 */

This syntax is good practice for objects that will only be used as arguments for the given method and need further documentation of each property. This cannot be used for @returns.
Example:
<html>  <head>    <title>        GeeksforGeeks    </title></head>  <body>    <center>        <h1 style="color:green">          GeeksforGeeks      </h1>        <button onclick="Hello(a, b)">          Hello      </button>        <script>            /**             * @param {Object} Obj  User information             * @param {string} Obj.a  name of user             * @param {number} Obj.b  number of user             */            function Hello(a, b) {                alert('User: ' + a + ', number:' + b);            };            var a = "name";            var b = 001;        </script>    </center></body>  </html>
Output:Before:After:
To document objects that will be used more than once in source:@typedef is useful in this situation. Once the type is defined in source, you can use it as a type for JSDoc tags like @param or @returns that make use of a type.Syntax:/**
 * @typedef {Object} Person
 * @property {number} age Length of time the person has lived
 * @property {string} name The word by which the person is addressed
 */
Can also be used in a @param tag:Syntax:/**
 * @param {Person} p - Description of p
 */
Can also be used in a @returns tag:Syntax:/**
 * @returns {Person} Description
 */
Example:<!DOCTYPE html><html>  <body>    <center>        <h1 style="color:green">          GeeksforGeeks      </h1>        <button onclick="Hello()">          Hello      </button>        <p id="demo"></p>          <script>           /**            * @typedef {Object} Person            * @property {number} age Length of time the person has lived            * @property {string} name The word by which the person is addressed            */           function Hello() {               document.getElementById(                 "demo").innerHTML = person.name + " " + person.age;           }           var person = {               name: "John",               lastName: "Doe",               age: 50,           };       </script>   </center>  </body>  </html>Output:Before:After:
Syntax:
/**
 * @typedef {Object} Person
 * @property {number} age Length of time the person has lived
 * @property {string} name The word by which the person is addressed
 */

Can also be used in a @param tag:
Syntax:
/**
 * @param {Person} p - Description of p
 */

Can also be used in a @returns tag:
Syntax:
/**
 * @returns {Person} Description
 */

Example:
<!DOCTYPE html><html>  <body>    <center>        <h1 style="color:green">          GeeksforGeeks      </h1>        <button onclick="Hello()">          Hello      </button>        <p id="demo"></p>          <script>           /**            * @typedef {Object} Person            * @property {number} age Length of time the person has lived            * @property {string} name The word by which the person is addressed            */           function Hello() {               document.getElementById(                 "demo").innerHTML = person.name + " " + person.age;           }           var person = {               name: "John",               lastName: "Doe",               age: 50,           };       </script>   </center>  </body>  </html>
Output:Before:After:
To document objects that have values of the same type:Syntax:/**
 * @param {Object.} Dict
 */
This syntax is good practice for objects whose values are all the same type. In this case, the first type i.e. string describes the type of JavaScript property (keys) that always remains of string type. The second type i.e. number describes the type of value, which can be of any type.This can also be used for @returns.
Syntax:
/**
 * @param {Object.} Dict
 */

This syntax is good practice for objects whose values are all the same type. In this case, the first type i.e. string describes the type of JavaScript property (keys) that always remains of string type. The second type i.e. number describes the type of value, which can be of any type.
This can also be used for @returns.
Picked
JavaScript
Web Technologies
Writing code in comment?
Please use ide.geeksforgeeks.org,
generate link and share the link here.
Remove elements from a JavaScript Array
Convert a string to an integer in JavaScript
Difference between var, let and const keywords in JavaScript
Differences between Functional Components and Class Components in React
How to append HTML code to a div using JavaScript ?
Remove elements from a JavaScript Array
Installation of Node.js on Linux
Convert a string to an integer in JavaScript
How to fetch data from an API in ReactJS ?
How to insert spaces/tabs in text using HTML/CSS?