Appearance
JSDoc documentation
We use JSDoc for our api documentation for controllers and services.
Accurate documentation makes it easier for all developers to work with our application code.
Here we have an example JSDoc comment for a function:
js
/**
* This is an example description of a function
* @param {string} paramName - Description of the param
* @param {object} obj
* @param {string} obj.firstParam - Description of the param
* @param {string} obj.secondParam - Description of the param
* @param {number} [obj.optionalParam] - Description of the param
*
* @returns {{reports: {data: {result: [], success: boolean}, data2: {result: [], success: boolean}}}}
*
* @throws A brief description of when the function might throw an error
*/
const exampleFunction = (paramName, { firstParam, secondParam, optionalParam = false }) => {
returns {
reports: {
data: {
result: [],
success: false,
},
data2: {
result: [],
success: true,
},
}
}
}/**
* This is an example description of a function
* @param {string} paramName - Description of the param
* @param {object} obj
* @param {string} obj.firstParam - Description of the param
* @param {string} obj.secondParam - Description of the param
* @param {number} [obj.optionalParam] - Description of the param
*
* @returns {{reports: {data: {result: [], success: boolean}, data2: {result: [], success: boolean}}}}
*
* @throws A brief description of when the function might throw an error
*/
const exampleFunction = (paramName, { firstParam, secondParam, optionalParam = false }) => {
returns {
reports: {
data: {
result: [],
success: false,
},
data2: {
result: [],
success: true,
},
}
}
}- Always include a high-level description of what the function does
- @params need to include a type and param name, with an optional description
- param descriptions should be aligned for readability
- For optional params, wrap the param name in square brackets
- For @returns, the returned object can be defined inline (as above), or in a typedef: see below
- @throws is optional, but useful for documenting the types of errors that can be thrown
Typedefs
For more complicated params or returns, it's useful to declare typedefs. Our implementation doesn't differ from the official docs, but here's an example non-the-less.
js
/**
* An example return object
* @typedef {object} ExampleObject
* @property {object} reports - Reports object with two data responses
* @property {object} data1 - An object
* @property {array} data1.result - An array of data1 values
* @property {boolean} data1.success - Outcome of loading data1
* @property {object} data2 - An object
* @property {array} data2.result - An array of data2 values
* @property {boolean} data1.success - Outcome of loading data2
*/
/**
* This is an example description of a function
* @param {string} paramName - Description of the param
* @param {object} obj
* @param {string} obj.firstParam - Description of the param
* @param {string} obj.secondParam - Description of the param
* @param {number} [obj.optionalParam] - Description of the param
*
* @returns {ExampleObject}
*
* @throws A brief description of when the function might throw an error
*/
const exampleFunction = (paramName, { firstParam, secondParam, optionalParam = false }) => {
returns {
reports: {
data: {
result: [],
success: false,
},
data2: {
result: [],
success: true,
},
}
}
}/**
* An example return object
* @typedef {object} ExampleObject
* @property {object} reports - Reports object with two data responses
* @property {object} data1 - An object
* @property {array} data1.result - An array of data1 values
* @property {boolean} data1.success - Outcome of loading data1
* @property {object} data2 - An object
* @property {array} data2.result - An array of data2 values
* @property {boolean} data1.success - Outcome of loading data2
*/
/**
* This is an example description of a function
* @param {string} paramName - Description of the param
* @param {object} obj
* @param {string} obj.firstParam - Description of the param
* @param {string} obj.secondParam - Description of the param
* @param {number} [obj.optionalParam] - Description of the param
*
* @returns {ExampleObject}
*
* @throws A brief description of when the function might throw an error
*/
const exampleFunction = (paramName, { firstParam, secondParam, optionalParam = false }) => {
returns {
reports: {
data: {
result: [],
success: false,
},
data2: {
result: [],
success: true,
},
}
}
}