What is the correct JSDoc syntax for a local variable?

Question

For a function like this...

function example() {
  var X = 100;

  ...

  var Y = 'abc';

  ...

  return Z;
}

I need to explain the purpose of some of the local variables. Adding a description like this...

function example() {
  /**
   * @description - Need to explain the purpose of X here.
   */
  var X = 100;

  ...

  /**
   * @description - Need to explain the purpose of Y here.
   */
  var Y = 'abc';

  ...

  return Z;
}

...doesn't seem to be getting picked up by JS Doc v3.4.0.

What is the correct syntax?

P.S. Some of my use cases call for multi-line comments.

as a side note.. https://refactoring.guru/smells/comments – YakovL Dec 08 '18 at 13:57 — YakovL, Dec 08 '18 at 13:57

score 65 · Answer 1 · answered Aug 01 '16 at 22:24

65

I usually use something like the code below in my projects.

function example() {
  /**
   * Need to explain the purpose of X here.
   * @type {number}
   */
  var X = 100;

  ...

  /**
   * Need to explain the purpose of Y here.
   * @type {string}
   */
  var Y = 'abc';

  ...

  return Z;
}

answered Aug 01 '16 at 22:24

mash

2,466
11
17

This is similar to PHPDoc: description, followed by `@var type`. Conversely, in both PHPDoc and JSDoc (AFAIK), function parameters are annotated the other way round: type first, then description. – Jake Jan 29 '23 at 00:37

vitaliytv · Answer 2 · 2022-03-21T16:22:36.430

34

one liner:

  /** @type {string} */
  let Y = 'abc';

edited Mar 21 '22 at 16:22

answered Jan 11 '20 at 06:59

vitaliytv

694
7
9

1

When answering an older question it is useful to explain what new aspect of the question your answer addresses. This answer doesn't say anything about what was said in the accepted answer, or indicate if the passage of time has changed the situation due to new versions of software coming out. – Jason Aller Jan 11 '20 at 07:33
2

This should be marked as the correct answer. To answer @vitaliytv and expand on the answer, yes it seems JS doc have expanded their support for inner members. This works for me. – viztastic Jun 08 '20 at 04:44
This is not the correct answer. The OP specifically asked how to include a description along with the type annotation. This does not answer that main question at all. – Jake Jan 29 '23 at 00:39

score 9 · Accepted Answer · answered Aug 05 '16 at 21:16

It seems that JS Docs ignores comments within the "block" (E.g. class, function, etc.). I tried...

@description
@inner
@instance
@member
@memberof
@name
@summary

...and others. I was unable to get any of them to generate documentation. Throughout the JS Doc examples they use normal JS comments for this sort of thing.

I have concluded that there is no official JS Doc syntax for this.

vljs · Answer 4 · 2020-03-10T23:33:12.790

3

Best thing that worked for me:

/**
  * @name AssetAutoGenerationOption
  * @type {"all" | "master" | "off"}
  */
export type AssetAutoGenerationOption = "all" | "master" | "off";

edited Mar 10 '20 at 23:33

answered Mar 10 '20 at 23:16

vljs

978
7
15

1

OP asked how to annotate a `var`, not an `export`. – Jake Jan 29 '23 at 00:32

score 0 · Answer 5 · edited Sep 09 '22 at 12:47

0

You might use:

/**
 * @function
 * @property {number} x - Need to explain the purpose of X here.
 * @property {number} y - Need to explain the purpose of Y here.
 * @returns {number} - Describe return value here (assumed number type for this example)
 */
function example() {
  var x
  var y = 'abc';
  return z;
}

You can also examine the official documentation here: https://jsdoc.app/about-getting-started.html#:~:text=JSDoc's%20purpose%20is%20to%20document,before%20the%20code%20being%20documented.

edited Sep 09 '22 at 12:47

Anthony

13,434
14
60
80

answered Jun 30 '21 at 15:26

Zippy

3,826
5
43
96

1

OP asked how to annotate a `var`, not a `function`. – Jake Jan 29 '23 at 00:31

What is the correct JSDoc syntax for a local variable?

5 Answers5

Linked