Добавление метаданных в вашу документацию
Предоставление хорошей документации является важной задачей для каждого разработчика. Это не только поможет вашим сверстникам быстро понять ваши рассуждения и, возможно, мыслительный процесс, но также поможет вам быстрее погрузиться в код, если вы вернетесь к нему через пару месяцев.
Поэтому я решил создать (неполный) список специальных тегов для использования с комментариями JSDoc. Это те, которые я лично использую чаще всего, и они доказали свою реальную пользу.
Базовый стартер
В следующем примере кода показан простой базовый пример, который следует использовать для каждой документации. Он аннотирует цель, параметры, а также тип возвращаемого значения.
/**
* Get a sum all terms provided.
*
* @param {...number} terms Array of terms to sum up.
* @returns {number} Sum of terms.
*/
export function sum(...terms: number[]){
return terms.reduce((acc,cv) => acc + cv, 0);
}
Пример кода в документации
Вы можете предоставить реальный пример встроенного кода с тегом «@example», чтобы сделать определенные варианты использования более понятными. Этот тег также можно использовать для быстрого отображения возможных пограничных случаев в реальном сценарии.
/**
* Get a sum all terms provided.
*
* @example
* ```ts
* import { sum } from "./source";
* const result = sum(40, 2);
* ```
*/
export function sum(...terms: number[]){
return terms.reduce((acc,cv) => acc + cv, 0);
}
Член какого модуля
Используйте тег «@memberOf», чтобы определить, какой модуль или родительская переменная содержит документированный код.
/**
* @memberOf module:source
*/
export function sum(...terms: number[]){
return terms.reduce((acc,cv) => acc + cv, 0);
}
Аннотация ссылки
Вы можете использовать тег «@see» вместе с тегом «@link», чтобы предоставить правильно отформатированную URL-документацию, вместо того, чтобы вставлять некоторые URL-адреса в основную документацию.
/**
* @see (@link module:source.sum}
* @see (@link https://www.some-source.com}
*/
export function sum(...terms: number[]){
return terms.reduce((acc,cv) => acc + cv, 0);
}
Документация общего типа
Если в вашем коде используются универсальные типы, вы можете использовать тег «@template» для определения имени универсального типа. Затем это имя используется в общих тегах «@param» в качестве ссылки на тип.
/**
* @template T
* @param {...T} Array of numbers to sum up.
* @returns {number} Sum of terms.
*/
export function sum(...terms: number[]){
return terms.reduce((acc,cv) => acc + cv, 0);
}
Определение автора фрагмента кода
В некоторых случаях важно также аннотировать автора. Это можно легко сделать с помощью тега «@author». Вы можете указать не только свое имя, но и адрес электронной почты в качестве контактной информации.
/**
* @author Tom Schönmann <tom@flaming.codes>
*/
export function sum(...terms: number[]){
return terms.reduce((acc,cv) => acc + cv, 0);
}
Устаревший код
О теге «@deprecated» рассказывать особо нечего, поскольку он делает именно то, что вы ожидаете. Этот тег обычно используется в API и может также ссылаться на новый код.
/**
* @deprecated Use 'add(...)' instead.
* @see {@link module:source/add}
*/
export function sum(...terms: number[]){
return terms.reduce((acc,cv) => acc + cv, 0);
}
Версия
Используйте тег «@version» для документирования версии данного кода. Обратите внимание, что этот тег ссылается не на версию приложения, а на собственную версию. Приращение этой версии означает, что этот конкретный код изменился.
/**
* @version 1.0.0
*/
export function sum(...terms: number[]){
return terms.reduce((acc,cv) => acc + cv, 0);
}
С тех пор, как код доступен для использования
Вы можете использовать тег «@since», чтобы документировать номер версии, из которой следующий код был добавлен в общедоступный API. Здесь важно отметить, что версия теперь ссылается на область приложения. Это отличается от прежнего тега «@version», который относится к конкретному кодовому блоку, который он документирует.
/**
* @since 2.0.1
*/
export function sum(...terms: number[]){
return terms.reduce((acc,cv) => acc + cv, 0);
}
