Блог

Я вижу, что некоторые люди пишут JSDoc для дженериков JavaScript, подобных этому (с точкой):

 /** @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, похоже, не распознает {<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.

Проверка статического типа в 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>} over {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.

Если {Array<string>} и {Array.<string>} действительно одно и то же (и я считаю, что это правда), то я бы предпочел первое последнему, чтобы значение . символа оставалось однозначным.

Согласно документации JSDoc синтаксис с точкой правильный. https://jsdoc.app/tags-type.html

Массив экземпляров MyClass.

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