How to describe “object” arguments in jsdoc?
Last Updated :
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>
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>
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>
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.
Like Article
Suggest improvement
Share your thoughts in the comments
Please Login to comment...