How to return void in JsDoc?
Solution 1
I don't believe you have to choose from a set of types in JsDoc... you can use any type name you wish (the curly braces indicate it's a type), so you can simply do:
@return {void}
Although, this is probably more correct for JavaScript:
@return {undefined}
Solution 2
Closure Compiler
According to the documentation of Google's Closure Compiler if nothing is being returned, the @return annotation should be omitted.
If there is no return value, do not use a @return tag.
Source: https://developers.google.com/closure/compiler/docs/js-for-compiler#tags
jsdoc-toolkit
However further documentation also states that the returnType and returnDescription are optional parameters.
returnType - Optional: the type of the return value.
returnDescription - Optional: any additional description.
Source: https://code.google.com/p/jsdoc-toolkit/wiki/TagReturns
Summary
You could either leave out the return annotation or include it without any parameters.
Solution 3
Looking at the ESlint docs they use
@returns {void}
Source: http://eslint.org/docs/rules/valid-jsdoc
Since I need to provide an @returns
for each function to pass tests in order to push code for certain projects this is required in my case.
Solution 4
If you need to say out loud that nothing is returned, you can say that in the free-form description. This is useful to clarify situations where a user might expect something to be returned. Of course proper naming of the function and the parameters should alone make the expected return type apparent, but it might not always be possible.
/**
* This is a funny function. Returns nothing.
* @param {string} a joke.
*/
var funny = function (joke) {
console.log(joke);
};
Tower
Updated on November 21, 2021Comments
-
Tower over 2 years
Is there a specified way to declare a method or a function to return void in JsDoc? Currently I am in the belief that
void
is the default return value, and other return values must be specifically provided:/** * @return {Integer} The identifier for ... */
-
Lucio Paiva almost 10 yearsThis answer is actually better than the accepted one. If your function doesn't return a result, you shouldn't say it returns
undefined
as this is already implicit in Javascript and may cause confusion to whoever reads your docs. -
hellboy over 9 yearsmay be also
@returns {void}
? -
Eugene almost 8 yearsWhat about returning
null
? -
BadHorsie almost 8 years@Eugene
null
is not necessarily the same asundefined
-
Shanimal over 7 years
@return {Void}
throws code inspection warning in IntelliJ IDE@return {undefined}
and@return {void}
does not. -
M. Eriksson over 6 years
null
is never the same asundefined
. When something is null, it is still defined but with no value. Undefined is, well, not defined :-) -
Aaron Mansheim over 6 yearsThe Ecmascript specifications list the language's types. The value returned by the
void
operator isundefined
. The name of the type of the valueundefined
isUndefined
, even thoughtypeof undefined
evaluates to"undefined"
. The nameVoid
is not defined in Ecmascript specifications. -
Mörre over 5 yearsNo, I disagree and say this is not a good idea. When something is missing you don't know if it was intentional or not. By being explicit about the return type even when it's
undefined
you force yourself to state your intent, also good when reading it later. Just to clarify, I'm not saying one should include a useless JS statement, I'm saying one should always include a JSDoc@returns
statement (I'm against useless code, but not against "useless" comments). -
GrayedFox almost 4 yearsIMO it makes sense to specify a return type of undefined if it is possible that your function or method returns any other value, in which case you get something like this:
@returns {Array|undefined} - returns array if operation successful, otherwise returns undefined
-
aljabear over 3 yearsI know it's not Python, but "explicit is better than implicit"
-
phoenixdown almost 3 yearseslint.org/docs/rules/valid-jsdoc - per the answer below should be
@returns {void}
not{Void}
and not{undefined}
. since this is top + accepted answer, would you consider editing? -
Paul about 2 years
eslint-plugin-jsdoc
gets unhappy if you leave out a@returns {void}