Skip to content

DOCUMENTATION_GUIDELINES.md

Latest commit

 

History

History
84 lines (59 loc) · 8.5 KB

DOCUMENTATION_GUIDELINES.md

File metadata and controls

84 lines (59 loc) · 8.5 KB

Руководство по написанию документации

Стандарты и процесс ведения документации. Обязательная структура каждого .md (что за скрипт, как использовать) задаётся в DOCUMENTATION.md — при добавлении или правке файла сверяйтесь с ним.

Подробные правила оформления (XML в коде, Tooltip/Header, шаблон .md-страницы, примеры) — в Docs/Оформление_документации.md.

1. Общие принципы

  • Язык в .md (Docs/): русский — пользовательская документация для инспектора Neoxider и репозитория.
  • Язык в коде (C#): XML ///, [Tooltip], [Header] и обычные комментарии к API — только английский (IntelliSense, единый стиль). Русские пояснения выносятся в Docs/…. Подробнее: таблица слоёв и примеры в Docs/Оформление_документации.md (§1–§3, §5).
  • Цель: в начале каждого файла сразу ясно что это и как использовать; дальше — поля, методы, события, примеры.
  • Стиль: сухо, по делу. Без лишних вводных и маркетинговых формулировок.

2. Структура и организация файлов

  • Русская документация — в папке Assets/Neoxider/Docs. Путь из этой папки указывается в атрибуте [NeoDoc("...")] (открывается из Inspector).
  • Английская документация — в папке Assets/Neoxider/DocsEn. Та же структура подпапок и имён файлов, что и в Docs/; содержимое — перевод или адаптация .md на английский. См. DocsEn/README.md.

Ниже — правила для основной (русской) документации в Docs.

  • Простые модули: Для каждого самостоятельного модуля (например, Audio, Bonus), который находится в своей папке в Assets/Neoxider/Scripts, создается один .md файл.

    • Пример: Assets/Neoxider/Scripts/Bonus -> Assets/Neoxider/Docs/Bonus.md

  • Сложные модули: Для модулей, содержащих множество скриптов и/или подпапок (например, Extensions, Tools), в Docs создается отдельная папка с тем же именем.

    • Внутри этой папки создается:
      1. README.md с кратким описанием всего раздела и ссылками на документацию по каждому скрипту. Если модуль содержит подпапки, README.md также должен содержать оглавление со ссылками на разделы этих подмодулей для быстрой навигации.
      2. Отдельный .md файл для каждого скрипта в модуле.
    • Пример: Assets/Neoxider/Scripts/Extensions -> Assets/Neoxider/Docs/Extensions/

3. Содержание файла документации

Обязательно: в начале каждого .md (сразу после заголовка H1) — блоки Что это и Как использовать (для документа по скрипту) или Что это и Оглавление (для README модуля). Подробная схема — DOCUMENTATION.md.

3.1. Обязательное начало (документ по скрипту)

  • Что это: тип (MonoBehaviour/ScriptableObject/класс), назначение, путь к файлу (.cs).
  • Как использовать: нумерованный список шагов (добавить компонент, назначить поля, вызвать метод, подписаться на событие).

3.2. Описание классов

Для каждого ключевого класса в модуле необходимо предоставить следующую информацию:

  1. Название класса (в формате заголовка, например, ### КлассНазвание).
  2. Пространство имен (Namespace) и Путь к файлу.
  3. Краткое описание: 1-2 предложения о назначении класса.
  4. Ключевые особенности (опционально): Список основных возможностей.
  5. Публичные свойства и поля (Public Properties and Fields): Список всех публичных свойств и полей с кратким описанием их назначения и типа данных.
  6. Публичные методы (Public Methods): Список публичных методов с кратким описанием. Обязательно указывайте, какой тип данных возвращает метод и что означает возвращаемое значение (например, Spend(float count) возвращает bool — true при успехе).
  7. Unity Events: Обязательно опишите все публичные UnityEvent. Укажите, когда вызывается событие и какие параметры (если есть) оно передает.

4. Рабочий процесс

Чтобы обеспечить точность и полноту документации, следуйте этому процессу:

  1. Анализ папки: Изучите целевую папку в Assets/Neoxider/Scripts, чтобы понять ее структуру и состав.
  2. Чтение по одному файлу: Внимательно читайте по одному файлу за раз. Это критически важно для глубокого понимания каждого скрипта перед тем, как его описывать.
  3. Написание документации: Следуя структуре, описанной в разделе 3, напишите текст документации.
  4. Запись в файл: Сохраните готовую документацию в соответствующий .md файл.

5. Обновление документации при изменениях

При перемещении или переименовании файлов скриптов необходимо обновить документацию:

  1. Обновление путей: Если скрипт был перемещен в другую папку, обновите путь к файлу в документации.
  • Пример: Если ScoreManager.cs был перенесен из Tools/Managers/ в Tools/Components/, обновите путь в соответствующем .md файле.
  1. Обновление ссылок: Проверьте и обновите все ссылки на перемещенный скрипт в других файлах документации (README файлы, связанные компоненты).
  2. Перемещение файла документации: Если скрипт перемещен в другую подпапку, рассмотрите возможность перемещения соответствующего .md файла документации в соответствующую структуру папок.
  • Пример: Если скрипт перенесен из Managers/ в Components/, документацию тоже следует переместить из Docs/Tools/Managers/ в Docs/Tools/Components/.