本地变量的正确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捕获到。

正确的语法是什么？

P.S.我的一些用例需要多行注释。

- Kirkland

---

作为一个附注，可以参考以下网址：https://refactoring.guru/smells/comments - YakovL

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

- mash

---

这与PHPDoc类似：描述，后跟@var type。相反，在PHPDoc和JSDoc（据我所知），函数参数的注释方式是相反的：首先是类型，然后是描述。 - Jake

Answer 2

一句话简述：

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

- vitaliytv

---

当回答一个较旧的问题时，解释你的答案涉及到问题的哪个新方面是很有用的。这个答案没有提到已接受答案中所说的内容，也没有表明时间的流逝是否因为新版本的软件而改变了情况。 - Jason Aller

这应该被标记为正确答案。回答@vitaliytv并扩展答案，是的，看起来JS doc已经扩展了对内部成员的支持。这对我很有效。 - viztastic

这不是正确的答案。OP明确要求如何在类型注释中包含描述，而这并没有回答主要问题。 - Jake

Answer 3

看起来 JS Docs 忽略了 "块"（例如类、函数等）内的注释。我尝试过...

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

...以及其他。我无法让它们生成文档。在JS Doc示例中，他们使用普通的JS注释来完成这件事。

我得出结论：没有官方的JS Doc语法来实现这个。

- Kirkland

Answer 4

对我最有效的方法：

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

- vljs

---

OP 问如何给 var 添加注释，而不是 export。 - Jake

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

您还可以在此处查看官方文档：https://jsdoc.app/about-getting-started.html#:~:text=JSDoc的目的是记录代码，使其易于阅读和理解。在编写代码之前，建议先编写文档。

- Zippy

---

OP 问如何给 var 注释，而不是 function。 - Jake