How to describe “object” arguments in jsdoc?

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.

  1. 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:

    filter_none

    edit
    close

    play_arrow

    link
    brightness_4
    code

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

    chevron_right

    
    

    Output:
    Before:

    After:

  2. 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:

    filter_none

    edit
    close

    play_arrow

    link
    brightness_4
    code

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

    chevron_right

    
    

    Output:
    Before:

    After:

  3. 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:

    filter_none

    edit
    close

    play_arrow

    link
    brightness_4
    code

    <!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>

    chevron_right

    
    

    Output:
    Before:

    After:

  4. 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.



My Personal Notes arrow_drop_up

Check out this Author's contributed articles.

If you like GeeksforGeeks and would like to contribute, you can also write an article using contribute.geeksforgeeks.org or mail your article to contribute@geeksforgeeks.org. See your article appearing on the GeeksforGeeks main page and help other Geeks.

Please Improve this article if you find anything incorrect by clicking on the "Improve Article" button below.




Article Tags :

Be the First to upvote.


Please write to us at contribute@geeksforgeeks.org to report any issue with the above content.