111

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 ...
 */
David Tang
  • 92,262
  • 30
  • 167
  • 149
Tower
  • 98,741
  • 129
  • 357
  • 507
  • https://eslint.org/docs/rules/valid-jsdoc says `@returns {void}` Ahhh someone already mentioned it: https://stackoverflow.com/a/45450508/470749 – Ryan Mar 28 '20 at 21:35

5 Answers5

125

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.

Community
  • 1
  • 1
Brent Robinson
  • 2,326
  • 1
  • 19
  • 14
  • 12
    This 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. – Lucio Paiva Jul 28 '14 at 00:30
  • 12
    No, 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). – Mörre Jan 20 '19 at 18:36
  • 2
    IMO 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` – GrayedFox Jul 08 '20 at 11:31
  • I know it's not Python, but "explicit is better than implicit" – allanberry Mar 21 '21 at 19:22
  • `eslint-plugin-jsdoc` gets unhappy if you leave out a `@returns {void}` – Paul May 18 '22 at 21:52
116

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}
Deejers
  • 3,087
  • 2
  • 23
  • 20
David Tang
  • 92,262
  • 30
  • 167
  • 149
  • may be also `@returns {void}` ? – hellboy Nov 06 '14 at 14:20
  • What about returning `null`? – Eugene Jul 12 '16 at 23:09
  • 9
    @Eugene `null` is not necessarily the same as `undefined` – BadHorsie Sep 13 '16 at 17:03
  • 8
    `@return {Void}` throws code inspection warning in IntelliJ IDE `@return {undefined}` and `@return {void}` does not. – Shanimal Dec 15 '16 at 18:14
  • 5
    `null` is never the same as `undefined`. When something is null, it is still defined but with no value. Undefined is, well, not defined :-) – M. Eriksson Nov 18 '17 at 22:12
  • 5
    The Ecmascript specifications list the language's types. The value returned by the `void` operator is `undefined`. The name of the type of the value `undefined` is `Undefined`, even though `typeof undefined` evaluates to `"undefined"`. The name `Void` is not defined in Ecmascript specifications. – Aaron Mansheim Dec 05 '17 at 19:14
  • 2
    eslint.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? – phoenixdown Sep 07 '21 at 20:43
28

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.

primetimejas
  • 471
  • 5
  • 9
1

To help to decide between the other answers, there is one benefit in explicitly written @return {void}. Although @return can be omitted, for a documenting coder, seeing the @return {void} works as a memory aid. It tells the coder that the return documentation is written. If there is no @return written, then the coder might need to inspect did he forget to write the return value documentation or does the function truly return nothing.

Of course, the return value documentation might be outdated. That is something the coder cannot directly know from the docs and needs to read the code to verify. Still, seeing the return value written gives the coder a bit of certainty that the documentation is correct and not just hastily written.

Akseli Palén
  • 27,244
  • 10
  • 65
  • 75
1

I find this less ambiguous than leaving out the @returns:

@returns {} Nothing is returned.

or even

@returns {} Nothing is returned because this is a broadcast receiver.

Just an idea.

Murrah
  • 1,508
  • 1
  • 13
  • 26