Правила ведения документации

Данный раздел обязателен для ознакомления всем, кто собирается описывать документацию для компонентов, хуков или типизации TypeScript.

Описание свойств компонентов и хуков в jsDoc

Все типы и интерфейсы TypeScript, которые будут экспортироваться, обязаны иметь описание jsDoc, так как весь текст для документации свойств компонента в Storybook будет сгенерирован из этого описания.

Для автоматизации проверки jsDoc в проекте используется плагин eslint-plugin-jsdoc. Основные ошибки в документации отображаются в IDE с помощью Prettier. В настоящее время все ошибки классифицируются как "warning", что не препятствует процессу сборки библиотеки.

Требования к описанию типов и интерфейсов

Описание типов и интерфейсов для компонента

Свойство компонента, которое является примитивом или объектом, должно иметь само описание свойства и следующие теги:

@inner - тег, определяющий, что свойство не является функцией;
Остальные желаемые необязательные теги, определяющие описание свойства, цель и назначение которых удовлетворяет семантике jsDoc.

Свойство компонента, которое является функцией, должно иметь само описание свойства и следующие теги:

@param - тег, определяющий аргумент функции. Каждый отдельный аргумент для функции должен описываться отдельно и в той же последовательности, что и сами аргументы функции. Также каждый аргумент должен иметь тип и соответствующее описание;
@returns - тег, определяющий возвращаемое значение. Также для возвращаемого значение обязательно должен быть определен тип и описание возвращаемого значения. Если тип возвращаемого значения равен void, то описание добавлять не нужно;
Остальные желаемые необязательные теги, определяющие описание свойства, цель и назначение которых удовлетворяет семантике jsDoc.

Описание типов и интерфейсов для хуков

Хук должен иметь описание и следующие теги:

@param - тег, определяющий аргумент функции. Каждый отдельный аргумент для функции должен описываться отдельно и в той же последовательности, что и сами аргументы функции. Также каждый аргумент должен иметь тип и соответствующее описание;
@returns - тег, определяющий возвращаемое значение. Также для возвращаемого значение обязательно должен быть определен тип и описание возвращаемого значения. Если тип возвращаемого значения равен void, то описание добавлять не нужно;
Остальные желаемые необязательные теги, определяющие описание свойства, цель и назначение которых удовлетворяет семантике jsDoc.

Общие требования к описанию jsDoc

Описание, параметры и прочий текст должен иметь в конце точку;
Каждая группа тегов должна начинаться с новой строки;
Теги имеют определенную очередность и соответствующую им группу. Полностью порядок тегов и их группы можно посмотреть в eslintrc.json в правиле jsdoc/sort-tags.

Описание свойств компонентов и хуков в Storybook

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

Концептуально документация поделена на 2 основных блока:

Блок с описанием компонента, принципов его работы и примерами использования;
Страница с API компонента.

Описание компонента или хука в mdx-файле

Название файла с документацией компонента

(Обязательно) Файл должен иметь название, реализующее следующий шаблон (название.story.mdx). Также название должно начинаться с буквы в нижнем регистре в camelCase.

Блок с заголовком документации компонента

(Обязательно) Заголовок компонента. Заголовок должен быть описан с помощью тега
Title
(пакет @storybook/addon-docs), например:
(Обязательно) Подзаголовок компонента. Текст должен быть не длинным, не надо добавлять туда все описание. Достаточно тезисно и кратко сформулировать работу компонента или хука. Подзаголовок должен быть описан с помощью тега
Subtitle
(пакет @storybook/addon-docs), например:
(Обязательно) Описание импорта этого компонента (пример, как импортировать из @v-uik/base и @v-uik/пакет-с-компонентом):
- Описание импорта должно быть написано с помощью тега
  Code
  (локальный пакет @v-uik/showroom/components), например:
- Свойства компонента
  Code
  : height="auto", withCopy={true}, kind="ghost";
- Импорт должен быть описан дважды (импорт из пакета @v-uik/base и @v-uik/пакет-с-компонентом)(как в примере выше).
Итоговый внешний вид документации блока с заголовком будет выглядеть так:

Блок с примерами

На данный момент в документации имеется четыре вида примеров: демонстрационные примеры, интерактивные примеры, примеры с выводом информации в консоль и примеры кода.

Демонстрационные примеры

Данный блок является приоритетным и добавляется в документацию, если есть возможность визуально продемонстрировать работу компонента с помощью простого примера. Данный блок содержит:

(Обязательно) Заголовок примера. Заголовок должен быть описан с помощью mdx-разметки начиная со второго уровня заголовков, например
## Название примера
;
(Обязательно) : Описание примера, которое должно содержать информацию о том, что демонстрирует пример, принципы его работы и необходимые действия с компонентом или хуком для корректного функционирования примера;
Дополнительно после текста и заголовка добавляется информационное сообщение, в котором описывается специфика работы примера, например:
или
(Обязательно) После текста идет пример в виде кода. Реализуется с помощью локального компонента
Preview
. Сам код компонента помещается в свойство code компонента Preview (пакет @v-uik/showroom/components), а сам пример в children. Пример:
Итоговый внешний вид документации блока с примером будет выглядеть так:
Первым примером обязательно является пример с заголовком Базовая функциональность, в котором будет реализован пример использование компонента с минимальным количеством свойств, необходимых для работы компонента.

Примеры с выводом информации в консоль

Данный блок добавляется в случае, когда необходимо отобразить пример, в котором необходимо вывести результат работы в консоль таким образом, чтобы это явно было видно пользователю, без необходимости использования консоли разработчика в самом браузере. Данный блок содержит:

(Обязательно) Заголовок примера. Заголовок должен быть описан с помощью mdx-разметки начиная со второго уровня заголовков, например
## Название примера
;
(Обязательно) : Описание примера, которое должно содержать информацию о том, что демонстрирует пример, принципы его работы и необходимые действия с компонентом или хуком для корректного функционирования примера;
Дополнительно после текста и заголовка добавляется информационное сообщение, в котором описывается специфика работы примера, например:
или
(Обязательно) После текста идет пример в виде кода. Реализуется с помощью локального компонента
Preview
. Сам код компонента помещается в свойство code компонента Preview (пакет @v-uik/showroom/components), а сам пример в children. Пример:
(Обязательно) для компонента
Preview
добавляется флаг withConsole. Также можно отредактировать информационное сообщение о том, что манипуляции с примером будут выведены в консоль через свойство alert.message;
(Обязательно) для компонента
Preview
используется паттерн Render Children, с помощью которого отрисовывается пример и передается функция-обработчик handleSubmit для передачи данных в консоль;
(Обязательно) В самом примере
Example
вызвать переданную функцию выше handleSubmit через которую необходимо записывать результат работы примера. Пример:
Итоговый внешний вид документации блока с примером с выводом результата в консоль будет выглядеть так:

Интерактивные примеры

Данный блок добавляется в случае, когда необходимо добавить для примера интерактивный интерфейс. Данный блок содержит:

(Обязательно) Заголовок примера mdx-разметки начиная со второго уровня заголовков с текстом «Интерактивный пример»:
(Обязательно) Компонент
Controls
(пакет @v-uik/showroom/components), который принимает свойства для настроек полей интерактивного примера и с помощью шаблона React Function As Children отрисовывает интерактивный пример, в котором обрабатываются получаемые значения свойств. Поля для интерактивного примера могут быть заданы как и на основе поддерживаемых свойств самого компонента, так и дополнительные, которые не фигурируют в типизации описываемого компонента. Пример:

Примеры кода

Данный блок добавляется в случае, когда визуальная демонстрация примера избыточна. В таком случае в качестве примера добавляется фрагмент кода. Данный блок содержит:

(Обязательно) Заголовок примера. Заголовок должен быть описан с помощью mdx-разметки начиная со второго уровня заголовков, например
## Название примера
;
(Обязательно) Текст, содержащий пояснения к коду и объясняющий принцип работы примера;
(Обязательно) Фрагмент кода, описанный с помощью компонента
Code
(пакет @v-uik/showroom/components). Пример:
(Обязательно) Свойства компонента
Code
: withShowCode={true}, showCodeKind="gradient".

Блок со связанными компонентами

Данный блок является обязательным в случае, если компонент использует внутри себя другие компоненты библиотеки. Оформляется в виде маркированного списка, соблюдающем следующие правила:

Элемент списка должен иметь такое же название, с каким он экспортируется из библиотеки (например Checkbox из пакета @v-uik/checkbox);
Если элемент списка не является последним, то в конце текста ставится точка с запятой ;;
Если элемент списка является последним, то в конце текста ставится точка;
Элементы списка должны быть остортированы в алфавитном порядке (от А до Я). Если в списке имеются и латинские символы, и кирилица, то сначала перечисляются все латинские названия, отсортированые в алфавитном порядке от A до Z. Потом перечисляются все кириллические названия, отсортированные в алфавитном порядке от А до Я.

Блок с полезными ссылками

Необязательный блок, в котором могут быть описаны ссылки на сторонние ресурсы. Оформляется в виде маркированного списка с соблюдением следующих правил:

Элемент списка должен быть описан на русском языке (не нужно в качестве текста просто вставлять URL страницы);
Если элемент списка не является последним, то в конце текста ставится точка с запятой ;;
Если элемент списка является последним, то в конце текста ставится точка;
Элементы списка должны быть остортированы в алфавитном порядке (от А до Я). Если в списке имеются и латинские символы, и кирилица, то сначала перечисляются все латинские названия, отсортированые в алфавитном порядке от A до Z. Потом перечисляются все кириллические названия, отсортированные в алфавитном порядке от А до Я.

Описание API компонента или хука в mdx-файле

Название файла c API

(Обязательно) Файл должен иметь название api.story.mdx.

Блок с заголовком API

(Обязательно) Заголовок. Заголовок должен быть описан с помощью тега
Title
(пакет @storybook/addon-docs) с текстом: «API». Пример:
(Обязательно) Подзаголовок API. Подзаголовок должен быть описан с помощью тега
Subtitle
(пакет @storybook/addon-docs) с текстом: «Описание свойств компонента и его элементов» (для компонента), или «Описание свойств хука». Пример:

Блок с API-таблицей компонента

(Обязательно) Заголовок типа с API. Заголовок должен быть описан с помощью mdx-разметки начиная со второго уровня заголовков, реализующий следующий шаблон:
- Если это тип компонента, то добавляется заголовок: НазваниеТипаКомпонента API;
- Если это тип хука, то добавляется заголовок: НазваниеТипаХука API, затем заголовки третьего уровня:
  - Если хук принимает несколько аргументов, то добавляется заголовок Args;
  - Если хук принимает только один аргумент, то добавляется заголовок Props;
  - Если хук возвращает значения, то добавляется заголовок Return value.
Если компонент принимает нативные свойства какого-либо HTML-элемента, то:
- Если это статический элемент, то:
  - Если компонент не принимает больше никакие свойства, кроме нативных, то добавляется следующий текст после заголовка: «Доступны свойства нативного компонента тег_элемента»;
  - Если компонент принимает и собственные свойства, и свойства нативного элемента, то добавляется следующий текст после заголовка: «Также доступны свойства нативного компонента тег_элемента».
- Если это полиморфный элемент, то:
  - Если компонент не принимает больше никакие свойства, кроме нативных, то добавляется следующий текст после заголовка: «Доступны свойства нативного компонента, переданного в свойство as, по умолчанию as = тег_элемента»;
  - Если компонент принимает и собственные свойства, и свойства нативного элемента, то добавляется следующий текст после заголовка: «Также доступны свойства нативного компонента, переданного в свойство as, по умолчанию as = тег_элемента».

Общие требования к описанию в .mdx

Все примеры в коде должны быть описаны на английском языке;
Текст документации должен быть написан без орфографических и синтаксических ошибок;
Документация описывается в повелительном наклонении во втором лице множественного числа (в вежливой форме);
Примеры должны быть понятными и простыми для восприятия;
В компонент Code нужно передавать код строкой с помощью фигурных скобок. Если код описан обычной строкой и он не был импортирован через raw-loader, то переходы на новую строку в коде нужно производить с помощью спецсимвола \n;
В качестве кавычек должны использоваться стрелки-елочки (« и » ).

Общие требования к ведению документации

Использовать только технически корректные названия на русском языке без транслитерации, например:
- prop - свойство;
- props - свойства;
- event - событие;
- callback - функция обратного вызова;
- handler - функция-обработчик;
- state - состояние;
- getter - функция для получения значения;
- setter - функция для задания значения;
- value - значение;
- default - значение по умолчанию;
- size - размер;
- hoc - компонент высшего порядка;
- hof - функция высшего порядка;
- merge - объединение.
Значения, которые получает функция при вызове, должны называться аргументами функции;
Свойства и значения для компонентов должны быть обернуты в теги кода («<code></code>» или «`» (в .mdx разметке или в jsDoc));
Буква ё должна быть заменена на e в русском языке;
Слово «тег» должно быть написано через букву e а не э;
Должны соблюдаться следующие правила маркированых списков:
- Если элемент списка не является последним, то в конце текста ставится точка с запятой;
- Если элемент списка является последним, то в конце текста ставится точка;
- Элементы списка должны быть остортированы в алфавитном порядке (от А до Я). Если в списке имеются и латинские символы, и кирилица, то сначала перечисляются все латинские названия, отсортированые в алфавитном порядке от A до Z. Потом перечисляются все кириллические названия, отсортированные в алфавитном порядке от А до Я.