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.

Solution 1

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.

Solution 2

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;
}

Solution 3

one liner:

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

Solution 4

Best thing that worked for me:

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

View more solutions