局部变量的正确 JSDoc 语法是什么？

Question

对于这样的功能......

function example() {
  var X = 100;

  ...

  var Y = 'abc';

  ...

  return Z;
}

我需要解释一些局部变量的用途。 添加这样的描述...

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

...似乎没有被JS Doc v3.4.0 。

什么是正确的语法？

PS 我的一些用例需要多行注释。

Answer 1

我通常在我的项目中使用类似下面的代码。

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

Answer 2

一个班轮：

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

Answer 3

JS Docs 似乎忽略了“块”中的注释（例如类、函数等）。 我试过...

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

...和其他人。 我无法让他们中的任何一个生成文档。 在整个 JS Doc 示例中，他们使用普通的 JS 注释来处理这类事情。

我已经得出结论，没有官方的 JS Doc 语法。

Answer 4

对我有用的最好的事情：

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

Answer 5

你可能会使用：

/**
 * @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;
}