JSDoc - How to document object with generic key names?

Question

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

You are in essence documenting a dictionary, so the duplicate above should apply — Icepickle, Jul 06 '17 at 14:02
@Icepickle I found the question rather being about naming convention / text issue, was that a wrong interpretation? — Teemu, Jul 06 '17 at 14:06
@Teemu From what I can read, he wants to know how he should document which object should be passed into the constructor, since he seems to be sending a dictionary in it (an object with a variable name), I am guessing that the duplicate should be correct. However, I am sure the OP could give his idea about it :) — Icepickle, Jul 06 '17 at 14:10
@Icepickle Could you take a look at my edited question, would this then be a correct way to document this? — HaSte, Jul 06 '17 at 15:21
This was actually just a dummy code, my code doesn't use people or peoples names. The keys in my case will be unique. — HaSte, Jul 06 '17 at 15:29

score 9 · Answer 1 · edited Jul 14 '23 at 13:57

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) {}
}

Just in case, @typedef supports its own type, too. For example, @typedef {Object} Person or @typedef {{}} Person which may be used instead of @type, therefore, omitted.

This is not possible if you want to use `@returns` – Tom Jul 03 '18 at 20:40 — Tom, Jul 03 '18 at 20:40

JSDoc - How to document object with generic key names?

1 Answers1