Что символ '@' делает в многострочных комментариях JavaScript? - PullRequest
Новая
       31

Что символ '@' делает в многострочных комментариях JavaScript?

0 голосов
/ 30 мая 2019

Просто очень любопытно, после того как я покопался в исходном коде Muuri и увидел это повсюду: 

var htmlCollectionType = '[object HTMLCollection]';
var nodeListType = '[object NodeList]';

/**
 * Check if a value is a node list
 *
 * @param {*} val
 * @returns {Boolean}
 */
export default function isNodeList(val) {
  var type = Object.prototype.toString.call(val);
  return type === htmlCollectionType || type === nodeListType;
}

@ param и @returns, похоже, на самом деле ничего не делают (я думаю), но онивыделены по-разному.Фактически, если вы посмотрите на код в git, они выделены , как будто они не являются комментариями .

Это какой-то синтаксис JavaScript, о котором я не знаю?Что тут происходит?Я хотел бы знать.

1 Ответ

2 голосов
/ 30 мая 2019

Это просто исключение JSDoc комментарии . На Stynax влияет Java, который имеет комментарии JavaDoc как часть стандарта. Короче говоря, комментарий документирует, что делает функция или метод, и имеет слегка специальный синтаксис - это блочный комментарий, который начинается с /** вместо простого /*, чтобы отличить его от обычного блочного комментария, и вы можете использовать некоторые аннотации для обозначения различных значений:

  • @param означает, что это параметр.
    • Значение внутри {} обозначает тип параметра - в этом случае * означает «любой», но вы должны документировать что-то вроде @param {string} или @param {number}
    • val - это имя параметра, который использует функция.
    • при желании вы можете добавить описание параметра, например, @param {*} val - used for foo and bar
  • @return документирует возврат функции.
    • значение внутри {} снова является типом. В этом случае логическое значение.
    • вы все еще можете добавить комментарий к возвращаемому значению, например: @returns {Boolean} true if correct, false if incorrect

Есть и другие вещи, которые вы можете задокументировать с использованием синтаксиса JSDoc, например, @copyright для указания лицензии или @throws для объявления ожидаемых исключений, которые может генерировать некоторый код. Некоторый синтаксис специфичен для функций или методов, другой - для объектов или даже целых файлов.

В общем, это попытка стандартизировать описания, оставленные в файлах. Вам не нужно что-либо делать с комментарием, но вы также можете использовать инструменты, которые читают комментарии и действуют на них - некоторые, например Tern.js , будут читать комментарии и пытаться проверьте, соответствует ли ваш код, например, если у вас есть 

/**
 * @param {number} bar
 * @return {boolean}
 */
function foo(bar) {}

и вы звоните foo("abc"), тогда вы можете получить предупреждение от инструмента, что вам следует передать номер. Или, если вы сделаете foo(123).replace("a", "b"), вы можете получить предупреждение о том, что вы пытаетесь использовать строковые методы для того, что должно быть логическим.

Другие инструменты могут вместо этого просто сканировать ваши файлы JS и генерировать документацию. Java делает это с JavaDoc - вы можете автоматически сгенерировать документацию для ваших методов и классов, основываясь на комментариях JavaDoc. Вы получите документацию в официальном стиле Java , что означает, что любая документация будет согласованной.

...