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
}
}
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.
You can use most JSDoc type syntax and any TypeScript syntax, from the most basic like string to the most advanced, like conditional types.
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.
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.
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) {}
}
If you love us? You can donate to us via Paypal or buy me a coffee so we can maintain and grow! Thank you!
Donate Us With