I'm writing some code comments using JSDoc style, and want to know what *=
implies in @returns {function(*=): *}
, which is generated by WebStorm.
I have tried to search the JSDoc wiki and usejsdoc.org but with no result.
Below is my code:
/**
* Get record data listener generator.
* @param {Function} createProps
* @returns {function(*=): *} // ** generated by webstorm **
*/
export function getRecordCustomDataListener(createProps) {
return (callback) => onRecordCustomData({ createRecordData: createProps })(callback); // `onRecordCustomData` has not default argument
}
I want to know what *=
implies in @returns {function(*=): *}
.
JSDoc comments are used for documentation lookup with Ctrl+Q in JavaScript and TypeScript, see JavaScript documentation look-up and TypeScript documentation look-up, as well as for type annotations and method return type hints in chained methods.
JSDoc tagsSpecifies the type of the object to which the keyword this refers within a function.
In JavaScript, single-line comments begin with // . It will ignore all the things immediately after // syntax until the end of that line. This is also known as inline commenting when we use // syntax alongside codes lines.
To comment on a parameter, start the line with @param , followed by the parameter's name, and then a short description of what the function will do.
See edit at the bottom!!
Testing it in WebStorm with a small snippet seems to indicate that *=
means a parameter is not optional and can be of any type where *
indicates that the parameter is of any type and optional. See the following example with generated jsdoc from WebStorm:
/**
*
* @param createProps
* @returns {function(*=, *): void}
*/
export function a(createProps) {
return (callback, callback2) => console.log(callback);
}
As you can see we are only using the first parameter callback
and leave callback2
unused. Webstorm generates the proper jsdoc for that.
The full jsdoc for our example above in english words: Return an arrow function that takes two parameters, a **not** optional first parameter that can be of any type, and an optional second parameter that can be of any type. That function returns void
Docs reference:
http://usejsdoc.org/tags-type.html
Optional parameter
An optional parameter named foo.
@param {number} [foo]
// or:
@param {number=} foo
An optional parameter foo with default value 1.
@param {number} [foo=1]
EDIT: The docs indicate that =
means optional parameter
but webstorm generates it with the opposite meaning. Either its wrongly documented or WebStorm does it wrong. I have tested it in WebStorm 2018.1
Build #WS-181.4203.535, built on March 22, 2018
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