This content originally appeared on Go Make Things and was authored by Go Make Things
I’m in the middle of running a 6-week workshop on how to structure and scale JavaScript, and one of my students asked a fantastic question that I wanted to share here.
They asked (I’m paraphrasing)…
If a function accepts an object as an argument, how do you document that objects properties with JSDoc?
Let’s dig in!
An example function
Here, we have an getWizardMessage() function. It accepts a wizard object as an argument.
For teaching purposes, this particular function just returns a string.
function getWizardMessage (wizard) {
let {name, spells, age} = wizard;
return `${name} is ${age} years old, and knows the following spells: ${spells.join(', ')}`;
}
To use the function, you pass in an object like this.
let wizard = {
name: 'Merlin',
age: 'Old AF',
spells: ['Dancing teacups', 'Turn into a fish', 'Talk to animals']
};
let msg = getWizardMessage(wizard);
Let’s look at how to document that.
Documenting a function with JSDoc
JSDoc is a popular approach to inline documentation used in many code bases.
It provides conventions for describing what a function does, the parameters it accepts (their expected format, what they are, and so on), and what it returns back out.
Here’s an example of how you might document the getWizardMessage() function with JSDoc.
/**
* Get the details about a wizard to render into the UI
* @param {Object} wizard The wizard data
* @return {String} The message about the wizard
*/
function getWizardMessage (wizard) {
let {name, spells, age} = wizard;
return `${name} is ${age} years old, and knows the following spells: ${spells.join(', ')}`;
}
As you can see, the docs include a description about what the function actually does, a @param tag that documents the wizard parameter, and a @return tag that documents what’s returned out of the function.
This is good, but it provides no detail about what the expected properties of the wizard object actually are.
Let’s fix that!
Documenting object properties with JSDoc
With JSDoc, if your parameter is an object with properties, you can optionally add @param tags for each of them using dot notation.
Here, we’ll add documentation for the wizard.name, wizard.spells, and wizard.age properties.
/**
* Get the details about a wizard to render into the UI
* @param {Object} wizard The wizard data
* @param {String} wizard.name The wizard's name
* @param {Array} wizard.spells A list of spells the wizard knows
* @param {Integer} wizard.age The wizards age
* @return {String} The message about the wizard
*/
function getWizardMessage (wizard) {
let {name, spells, age} = wizard;
return `${name} is ${age} years old, and knows the following spells: ${spells.join(', ')}`;
}
Now, a developer using this function has a much more clear picture of how the function works, and what expectations are for arguments passed into it.
Get unlimited access to a JavaScript expert. If you're working on a critical project, I can help you reduce your risk and avoid costly delays caused by common mistakes. Learn more about consulting with me.
This content originally appeared on Go Make Things and was authored by Go Make Things
Go Make Things | Sciencx (2022-10-18T14:30:00+00:00) How to document object properties with JSDoc. Retrieved from https://www.scien.cx/2022/10/18/how-to-document-object-properties-with-jsdoc/
Please log in to upload a file.
There are no updates yet.
Click the Upload button above to add an update.