Logo Questions Linux Laravel Mysql Ubuntu Git Menu
 

JSDoc - How to document object with generic key names? [duplicate]

I need to document an ES6 class with JSDoc that takes in an object that has properties that has the key names as names of people so the key names can be pretty much any string, nothing predefined. So the structure of the object should be like the following:

{
    "Name of person": {
        "age": 31,
        "hobby": "Tennis"
    },
    "Name of another person": {
        "age": 29,
        "hobby": "Running"
    }
}

So the name of each person is a key but it can be anything at all, it's not predefined. An example of what I'm trying to document:

class ExampleClass {
    /**
     * Creates an instance of ExampleClass
     * @param {Object} peopleObj            - Contains information about people.
     * @param {String} peopleObj.name       - The name of the person. <----- how should this be documented?
     * @param {Number} peopleObj.name.age   - The age of the person.
     * @param {String} peopleObj.name.hobby - The hobby of the person.
     * @memberof ExampleClass
     */
    constructor(peopleObj) {
        // Do stuff
    }
}

I feel like if I put "peopleObj.name" it implies that the key should be "name" but not any name you like. So how do I document this with letting the user know that he can insert any name he likes there?


EDIT

For anyone wondering, this is how I ended up documenting this (can't add it as answer since someone closed this question).

/**
* Information about a single person.
* @typedef Person
* @type {object}
* @property {number} age   - The age of the person.
* @property {string} hobby - The hobby of the person.
*/
class ExampleClass {
    /**
     * Creates an instance of ExampleClass.
     * @param {Object.<string, Person>} peopleObj - Information about people as {@link Person}
     *                                              objects where the key is their name.
     * @memberof ExampleClass
     */
    constructor(peopleObj) {
        // Do stuff
    }
}
like image 973
HaSte Avatar asked Jul 06 '17 11:07

HaSte


People also ask

How to specify type in JSDoc?

The @type tag allows you to provide a type expression identifying the type of value that a symbol may contain, or the type of value returned by a function. You can also include type expressions with many other JSDoc tags, such as the @param tag.

Can you use JSDoc with TypeScript?

You can use most JSDoc type syntax and any TypeScript syntax, from the most basic like string to the most advanced, like conditional types.

What are JSDoc tags?

JSDoc is a markup language used to annotate JavaScript source code files. Using comments containing JSDoc, programmers can add documentation describing the application programming interface of the code they're creating.

Why should I use JSDoc?

JsDoc is a great tool for documenting code and providing type-safety in your JavaScript project without any additional configuration. Learn what JsDoc is, how it works, the benefits it provides, and how to use it in your project.


1 Answers

What you are describing is covered in the @type JSDoc documentation.

The object should be documented as follows:

/**
 * @typedef Person
 * @type {Object}
 * @property {number} age - the person's age
 * @property {string} hobby - the person's hobby
 */

/** 
 * ExampleClass
 */
class ExampleClass {

    /**
     * Creates a dictionary of people
     * @param {Object.<string, Person>} peopleObj - an object with names as keys and Person objects as values. 
     * @memberof ExampleClass
     */
     constructor(peopleObj) {}
}
like image 104
Gerrit0 Avatar answered Sep 17 '22 07:09

Gerrit0