Nrgy.js

Русский

English

Русский

English

Оформление

Требования к документированию для разработчиков ​

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

Общие правила ​

  1. Размещение документации: Файлы документации по исходному коду должны размещаться в той же папке, что и сам исходный файл.
  • Пример: packages/core/src/reactivity.ts -> packages/core/src/reactivity.md.
  1. Локализация: Необходимо предоставлять перевод документации на английский и русский язык. Допускается перевод через AI.
  • Перевод должен размещаться в отдельном файле с локалью в качестве суффикса.
  • Пример: packages/core/src/reactivity.ru.md.

  1. Формат: Документация пишется в формате Markdown.

  2. Запрет на статьи для index.ts: Не создавайте отдельные файлы документации для исходных файлов index.ts.

  • Публичные точки входа пакета, такие как index.ts, должны описываться в пакетном README.md или в другой пакетной документации верхнего уровня.

Структура статьи для файла (модуля) ​

Каждая статья должна содержать следующие разделы:

  1. Назначение файла (Purpose): Краткое описание того, какую задачу решает данный файл/модуль.
  2. Общая информация (Overview): Более детальное описание логики работы, контекст использования.
  3. Концептуальная архитектура (Conceptual Architecture): Описание внутренних механизмов, связей с другими частями системы.
  4. Описание публичного API (Public API Description): Список экспортируемых функций, классов, типов с описанием параметров и возвращаемых значений.
  5. Примеры использования (Usage Examples): Практические примеры кода (Code Blocks), демонстрирующие использование API.

Структура статьи для пакета ​

Для каждого пакета в его корне (обычно рядом с index.ts или в корне папки пакета) должен быть файл README.md (или index.md в общей папке docs), содержащий:

  1. Назначение пакета: Зачем нужен этот пакет.
  2. Общая информация: Основные идеи и принципы.
  3. Установка пакета: Команды для установки (npm/yarn/pnpm).
  4. Концептуальная архитектура: Как пакет устроен внутри.
  5. Документация по функционалу: Ссылки на ключевые модули или сводное описание.
  6. Примеры использования: Интеграционные примеры.

Стиль написания ​

  • Используйте четкий и лаконичный технический язык.
  • Код в примерах должен быть рабочим и соответствовать стандартам проекта.
  • Для API используйте форматирование inline code для имен функций и параметров.