JSDoc 泛型中什么时候应该有一个点？

如何解决JSDoc 泛型中什么时候应该有一个点？

我看到有些人为这样的 JavaScript 泛型编写 JSDoc（带有一个点）：

/** @param {Array.<Bar>} bars the bars that should be fooed*/
function foo(bars) {}

和其他类似的（没有点）：

/** @param {Array<Bar>} bars the bars that should be fooed*/
function foo(bars) {}

点的意义是什么？哪个版本是正确的？什么时候该用，什么时候不该用？

解决方法

从语法的角度来看，当您运行 jsdoc index.js

时，所有这些类型的表达式都是有效的

/** @param {Array} x */
const a = x => x;

/** @param {Array.<string>} x */
const b = x => x;

/** @param {Array<string>} x */
const c = x => x;

/** @param {string[]} x */
const d = x => x;

应该注意的是，Google Closure Compiler 似乎无法识别 {<type>[]} 类型表达式，例如如果你编译这个：

/** @param {string[]} x */
const a = x => x;

您收到以下警告：

JSC_TYPE_PARSE_ERROR: Bad type annotation. expected closing } See https://github.com/google/closure-compiler/wiki/Annotating-JavaScript-for-the-Closure-Compiler for more information. at line 1 character 18
/** @param {string[]} x */
                  ^
JSC_TYPE_PARSE_ERROR: Bad type annotation. expecting a variable name in a @param tag. See https://github.com/google/closure-compiler/wiki/Annotating-JavaScript-for-the-Closure-Compiler for more information. at line 1 character 18
/** @param {string[]} x */
                  ^

查看这个 Google Closure Compiler fiddle。

VS Code 中的静态类型检查器会抱怨最后三个函数调用：

// @ts-check

/** @param {Array} x */
const a = x => x;

/** @param {Array.<string>} x */
const b = x => x;

/** @param {Array<string>} x */
const c = x => x;

/** @param {string[]} x */
const d = x => x;

a(['foo',3]); // OK (we just need an array)
b(['foo',3]); // ERR: 3 is not a string
c(['foo',3]); // ERR: 3 is not a string
d(['foo',3]); // ERR: 3 is not a string

所以看起来 {Array.<string>} 和 {Array<string>} 是一回事。

我个人更喜欢{Array<string>}而不是{Array.<string>}。为什么？点 . 也是一个“命名空间”分隔符：

/** @namespace */
const Burrito = {};

/** @constructor */
Burrito.beef = function () {};

/** @param {Burrito.beef} x */
const a = x => x;

a("foo");
a(new Burrito.beef());

Google Closure 编译器会针对第一次调用发出警告（第二次调用没问题）：

JSC_TYPE_MISMATCH: actual parameter 1 of a does not match formal parameter
found   : string
required: (Burrito.beef|null) at line 10 character 2
a("foo");
  ^

查看这个 Google Closure Compiler fiddle。

如果 {Array<string>} 和 {Array.<string>} 真的是同一个东西（我相信这是真的）那么我会更喜欢前者而不是后者，以保持 {{1} 的含义} 字符明确。

,

根据 JSDoc 文档，带点的语法是正确的。 https://jsdoc.app/tags-type.html

一组 MyClass 实例。

{Array.<MyClass>}
// or:
{MyClass[]}