Автор оригинала: Guillaume Martigny.
Многие разработчики жалуются на слабое набрав JavaScript (по причинам). Вот почему мы видели подъемники. Но в качестве аккуратного, как есть, Tybrescript поставляется с некоторыми предостережениями.
- Трудно печатать
- Ваш код анализируется и изменен
- Дополнительный шаг для построения
- Новый синтаксис для изучения
Большую часть времени их легко иметь дело или просто игнорировать. Где jsdoc действительно хорош, состоит в том, что он уменьшает боль слабого типа без каких-либо недостатков и даже добавить к столу.
Что это
Во-первых, давайте посмотрим сложный пример, который мы собираемся реконструировать вдоль этого урока.
/**
* Nice little equine animal
* @class
* @extends Animal
*/
class Pony extends Animal {
/**
* Pony constructor
* @param {String} name - This pony's name
* @param {String} [color=Pony.colors.white] - This pony's color
*/
constructor (name, color = Pony.colors.white) {
super(name);
this.color = color;
/**
* This pony's age
* @type {Number}
*/
this.age = 0;
}
/**
* Make it run
* @param {...String} through - Any number of field to run through
* @example instance.run("field", "land");
* @return {Pony} Itself
*/
run (...through) {
console.log("Run through ", ...through);
return this;
}
/**
* @typedef {Object} PonyColors
* @prop {String} white - Pure light color
* @prop {String} black - Dark color
* @prop {String} foxy - Reddish color
*/
/**
* Get possible pony's colors
* @static
* @return {PonyColors}
*/
static get colors () {
return {
white: "#fff",
black: "#333",
foxy: "#c57432",
};
}
}
И вот демонстрация преимуществ (с использованием веб-таблицы). Посмотрите внимательно на автозаполненные всплывающие подсказки.
Теперь давайте пройдемся через это шаг за шагом.
Описание
Самое простое использование jsdoc – описать функцию или класс.
/**
* Nice little equine animal
*/
class Pony extends Animal {
/**
* Pony constructor
*/
constructor (name, color = Pony.colors.white) {
// ...
}
/**
* Make it run
*/
run (...through) {
// ...
}
/**
* Get possible pony's colors
*/
static get colors () {
// ...
}
}
Теперь любой, кто использует код, который вы написали, будет иметь некоторую информацию с целью каждой функции или классов. В зависимости от вашего IDE или редактора, он будет показан в подсказке при поддержке автозаполнения.
Параметры
Во введении я говорил о типах переменных в JS. Вот где мы решаем проблему. JSDOC позволяет вам указать, какие параметры с помощью чего тип (или типы) ожидают функцией. Затем ваша среда разработки должна предупредить вас, если вы дадите параметр с несовместимым типом.
/**
* Pony constructor
* @param {String} name - A string
* @param {String|Number} color - A string or a number
*/
constructor (name, color = Pony.colors.white) {
// ...
}
В то же время вы можете быстрое описание использования переменной. Если параметр является необязательным, просто окружайте его кронштейн и укажите значение по умолчанию, если это необходимо.
/**
* Pony constructor
* @param {String} name - This pony's name
* @param {String} [color=Pony.colors.white] - This pony's color
*/
constructor (name, color = Pony.colors.white) {
// ...
}
Мы снова можем видеть эффект, на автозаполнении.
Тип/Определение обратного вызова
Иногда вам может потребоваться определить пользовательские типы для описания некоторых данных, которые вы не хотите обернуть в классе.
/**
* @typedef {Object} PonyColors
* @prop {String} white - Pure light color
* @prop {String} black - Dark color
* @prop {String} foxy - Reddish color
*/
Таким образом, вы можете прикрепить тип и описание каждому элементу объекта.
То же самое верно для ожидаемого параметра, рассмотрим следующее:
/**
* @typedef {Object} CustomData
* @prop {String} name - Cute name for you pony
* @prop {String} [color=Pony.colors.white] - Color of its fur
* @prop {Number} [age=0] - Years since its birth
*/
/**
* Create a pony
* @param {CustomData} data
* @return Pony
*/
function ponyFactory (data) {
// ...
}
CustomData Тип объясняется в блоке @typedef. Тип определения может событие продлевает другие с тегом @extends. Это действительно круто 8)
Если функция ожидает обратного вызова (например, типичный массив, например), вы можете показать, какие параметры будут переданы на этот обратный вызов.
/**
* @callback PonyCallback
* @param {Pony} pony - A pony
* @param {Number} index - Index of the pony
* @param {Array} list - List of all the ponies
*/
/**
* Execute a function on each created pony
* @param {PonyCallback} callback - Function called on each pony
*/
function herd (callback) {
// ...
}
Дальше и дальше
Документация JSDOC имеет много тегов для вас использовать. Каждый, который позволяет вам лучше сообщить пользователям вашего кода.
Почетный упоминание @return (определите возвращенный тип), @Abstract (этот класс не должен быть мстительным), @Type (укажите тип для любой переменной), @example (показать пример использования) …
Помните, большую часть времени вы будете поддерживать свой собственный код. Так что на самом деле вы делаете услугу для себя, документируя код, который вы пишете.
И последнее, но не менее важное, есть многочисленные способы Чтобы разобрать всю документацию и вывод полностью отформатированной усадки для документирования вашего API.