With JSDoc we can add comments & parameter types to functions and VSCode intellisense will pick it up. Syntax
// @ts-check
/**
* @summary Does something.
* @description
* This is a long description.
* - Example bullet
* - Example bullet
* @param {number} a First number
* @param {number} b Second number
* @returns {number} Sum value
*/
function sum(a, b) {
return a + b
}
sum(1, '2')
Snippet in VSCode Type /** before the function and snippet with relative parameters will be pasted. Snippet suggestion
// settings.json
"javascript.suggest.completeJSDocs": true
Type checking In file Type on top of js file // @ts-check . In project
// jsconfig.json or tsconfig.json
{
"compilerOptions": {
"allowJs": true,
"checkJs": true
}
}
Everywhere In VSCode settings
// settings.json
"js/ts.implicitProjectConfig.checkJs": true,
"typescript.validate.enable": true,
"javascript.validate.enable": true,
Types @param {boolean} boolean @param {(number|boolean)} multiple types (type union) @param {string[]} array of strings @param {?number} number or null @param {!number} number, but never null @param {{a: number, b: string, c}} myObj object with properties or
@param {Object} myObj
@param {number} myObj.a
@param {string} myObj.b
@param {*} myObj.c
@param {...number} num many numeric parameters @param {number} [foo] optional parameter named foo @param {number} [foo=1] optional parameter foo with default value 1 Callback
/**
* @callback myCallback
* @param {number} x - ...
*/
/** @type {myCallback} */
Type definition
/**
* @typedef PropertiesHash
* @type {object}
* @property {string} id - an ID
* @property {string} name - your name
* @property {number} age - your age
*/
/** @type {PropertiesHash} */
Object with parameter
/**
* function sums two values passed in object { a: 1, b: 2 }
* @param {Object} vals - object with values 'a' and 'b'
* @param {number} vals.a 1st number
* @param {number} vals.b 2n number
* @returns {number} sum value
*/
function sum(vals) {
return vals.a + vals.b
}
sum({ a: 2, b: 3 })
Object with destructured parameters
/**
* function sums two values passed in object { a: 1, b: 2 }
* @param {Object} param - object with values 'a' and 'b'
* @param {number} param.a 1st number
* @param {number} param.b 2n number
* @returns {number} sum value
*/
function sum({ a, b }) {
return a + b
}
sum({ a: 2, b: 3 })
Array of objects
/**
* Assign the project to a list of employees.
* @param {Object[]} employees - The employees who are responsible for the project.
* @param {string} employees[].name - The name of an employee.
* @param {string} employees[].department - The employee's department.
*/
function allNames(employees) {
return employees.map(employee => employee.name).join('; ')
}
const companyWorkers = [
{ name: 'John', department: 'sales' },
{ name: 'Kate', department: 'sales' }
]
allNames(companyWorkers)
Optional parameter
/**
* @param {string} [somebody] - Somebody's name.
*/
function sayHello(somebody) {
if (!somebody) {
somebody = 'John Doe'
}
alert('Hello ' + somebody)
}
optional parameter and default value
/**
* @param {string} [somebody=John Doe] - Somebody's name.
*/
function sayHello(somebody) {
if (!somebody) {
somebody = 'John Doe'
}
alert('Hello ' + somebody)
}
Any type
/**
* @param {*} somebody - Whatever you want.
*/
function sayHello(somebody) {
console.log('Hello ' + JSON.stringify(somebody))
}
one OR another type
/**
* @param {(string|string[])} [somebody=John Doe] - Somebody's name, or an array of names.
*/
function sayHello(somebody) {
if (!somebody) {
somebody = 'John Doe'
} else if (Array.isArray(somebody)) {
somebody = somebody.join(', ')
}
alert('Hello ' + somebody)
}
Repeating parameter
/**
* Returns the sum of all numbers passed to the function
* @param {...number} num - A positive or negative number
*/
function sum(num) {
let sum = 0
for (let i=0; i < arguments.length; i++) {
sum += arguments[i]
}
return sum
}
sum(1, 2, 3)
Callback
/**
* This callback type is called "requestCallback" and is displayed as a global symbol
*
* @callback requestCallback
* @param {string} responseCode
* @param {string} responseMessage
*/
/**
* Does something asynchronously and executes the callback on completion
* @param {requestCallback} helloCallBack - The callback that handles the response
*/
function doSomethingAsynchronously(helloCallBack) {
helloCallBack('hi', 'man')
}
doSomethingAsynchronously((a, b) => alert(a + ' ' + b))
Return multiple types
/**
* Returns the sum of a and b
* @param {number} a
* @param {number} b
* @param {boolean} retArr If set to true, the function will return an array
* @returns {(number|Array)} Sum of a and b or an array that contains a, b and the sum of a and b
*/
function sum(a, b, retArr) {
if (retArr) {
return [a, b, a + b]
}
return a + b
}
Returns promise
/**
* Returns the sum of a and b
* @param {number} a
* @param {number} b
* @returns {Promise} Promise object represents the sum of a and b
*/
function sumAsync(a, b) {
return new Promise(function(resolve, reject) {
resolve(a + b)
}
typedef
/**
* A number, or a string containing a number
* @typedef {(number|string)} NumberLike
*/
/**
* Set the magic number
* @param {NumberLike} x - The magic number
*/
function setMagicNumber(x) {
}
/**
* The complete Triforce, or one or more components of the Triforce.
* @typedef {Object} WishGranter~Triforce
* @property {boolean} hasCourage - Indicates whether the Courage component is present.
* @property {boolean} hasPower - Indicates whether the Power component is present.
* @property {boolean} hasWisdom - Indicates whether the Wisdom component is present.
*/
/**
* A class for granting wishes, powered by the Triforce.
* @class
* @param {...WishGranter~Triforce} triforce - One to three {@link WishGranter~Triforce} objects
* containing all three components of the Triforce.
*/
function WishGranter(triforce) {}
constant
/**
* Color red
* @constant
* @type {string}
* @default
*/
const RED = 'FF0000'
example
/**
* Solves equations of the form a * x = b
* @example <caption>Example usage of method1.</caption>
* // returns 2
* globalNS.method1(5, 10);
* @returns {Number} Returns the value of x for the equation.
*/
globalNS.method1 = function (a, b) {
return b / a;
};
exports
/**
* A module that says hello!
* @module hello/world
*/
/** Say hello. */
exports.sayHello = function() {
return 'Hello world';
};
/**
* A module that shouts hello!
* @module hello/world
*/
/** SAY HELLO. */
module.exports = function() {
return "HELLO WORLD";
};
function Marks an object as being a function, even though it may not appear to be one to the parser.
/**
* @function paginate paginateFactory wrapper
*/
const paginate = paginateFactory(pages)