Как я могу пометить параметр как содержащий DOM node в JSDoc?

Я хочу указать, что параметр должен быть DOM node, но я не могу найти никакой информации о том, как указать это с помощью JSDoc. Я мог бы просто использовать {Object}, но это довольно уродливо. Я бы предпочел бы что-то вроде {Node} или {DOMNode}, но я не могу найти никаких примеров, чтобы указать мне в этом направлении.

Итак, как я могу пометить параметр как ожидающий DOM node?

Ответы

Ответ 1

Из jsdoc.app для аннотации @type:

Выражение типа может включать путь имени JSDoc к символу (например, myNamespace.MyClass); встроенный тип JavaScript (например, строка); или их комбинация. Вы можете использовать любое выражение типа компилятора Google Closure, а также несколько других форматов, специфичных для JSDoc.

[...]

Каждый тип указывается путем предоставления выражения типа с использованием одного из форматов, описанных ниже. Где это уместно, JSDoc автоматически создает ссылки на документацию для других символов. Например, @type {MyClass} будет ссылаться на документацию MyClass, если этот символ был задокументирован.

Так что вы можете ссылаться на символы. HTMLElement (и наследующие объекты, такие как HTMLImageElement) являются символами. Поэтому, если вы следуете спецификации, вам должно быть разрешено делать:

@type {HTMLElement}

чтобы указать, что типом чего-либо является HTMLElement (то есть узел DOM).

Я предполагаю, почему это явно не задокументировано, потому что объекты узла DOM не являются встроенными в JavaScript (например, String или Number). Они добавляются клиентским браузером, поэтому они технически похожи на любой другой символ, который вы и я могли бы создать (будучи реализованным с использованием кода собственного браузера), если говорить о спецификации языка JS.

Хотя мы еще не дошли до стадии фактического составления нашей документации (это отдельная история), которая подтвердила бы, действительно ли вышеизложенное действительно принимается JSDoc, именно так мы интерпретируем и следуем этой конкретной концепции, в которой я работаю, и нашему стандарту. IDE (IntelliJ) принимает это.

Ответ 2

Если вы хотите что-то, на что пользователь может щелкнуть, и, возможно, следуйте ссылке на документацию, вы можете использовать @external:

/**
 * A node in the DOM tree.
 *
 * @external Node
 * @see {@link https://developer.mozilla.org/en-US/docs/Web/API/Node Node}
 */

/**
 * @param {external:Node} node
 */
function foo(node) {
}

Я не беспокоюсь об этом и просто отмечаю такие параметры {Node}. Весь мой код находится в модулях, поэтому типы, которые я определяю, начинаются с module:. Поэтому даже если бы у меня был класс с именем Node, он выглядел бы как module:foo~Node, если он определен в foo.