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

Question

我看到有人为 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) {}

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

Answer 1

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

MyClass 实例数组。

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

Answer 2

从语法的角度来看，当您运行 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 闭包编译器 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闭包编译器将发出关于第一次调用的警告（第二次调用没问题）：

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 闭包编译器 fiddle。

如果 {Array<string>} 和 {Array.<string>} 真的是同一件事（我相信这是真的）那么我会更倾向于前者而不是后者以保持 [= 的含义22=] 字符明确.

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

When should there be a dot in JSDoc generics?

javascript

jsdoc