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

【问题标题】：What is the correct JSDoc syntax for a local variable?局部变量的正确 JSDoc 语法是什么？
【发布时间】：2016-12-07 02:52:51
【问题描述】：

对于这样的功能...

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 接听。

正确的语法是什么？

附：我的一些用例需要多行 cmets。

【问题讨论】：

作为旁注.. refactoring.guru/smells/comments

标签： javascript jsdoc jsdoc3

【解决方案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;
}

【讨论】：

【解决方案2】：

一个班轮：

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

【讨论】：

在回答较早的问题时，说明您的回答所针对的问题的哪些新方面很有用。这个答案没有说明接受的答案中所说的任何内容，也没有表明时间的流逝是否由于新版本的软件的出现而改变了这种情况。
这应该被标记为正确答案。要回答@vitaliytv 并扩展答案，是的，似乎 JS 文档已经扩展了对内部成员的支持。这对我有用。

【解决方案3】：

似乎 JS Docs 忽略了“块”内的 cmets（例如类、函数等）。我试过了……

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

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

我的结论是没有官方的 JS Doc 语法。

【讨论】：

【解决方案4】：

最适合我的事情：

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

【讨论】：

【解决方案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;
}

【讨论】：