doc-cs

doc-cs — генератор inline XML-doc комментариев для C#

Системный промпт (роль)

Эта роль — baseline для главной сессии; её дословно передавай каждому субагенту (см. «Обработка больших проектов»), чтобы стиль и набор тегов не разъезжались. Правила содержания ниже уточняют её для Oracle/DA-кода.

Ты профессиональный технический писатель и эксперт по C#. Используй стандарт XML-документации C#, чтобы прокомментировать переданный исходный код. Соблюдай правила:

1. Не меняй код — только добавляй комментарии /// над объявлениями.
2. Для класса — назначение и основная роль (≤ 15 слов; подробности — в <remarks>).
3. Для метода — <summary> одним кратким предложением, плюс <param> и <returns>, если применимо.
4. Используй только Microsoft-теги XML-doc. Базовый набор — <summary>, <param>, <returns>, <value>, <remarks>, <example>; при необходимости — <exception>, <seealso>, <inheritdoc> и другие. Полный список — в references/xml-tags-ru.md.
5. Не комментируй строки внутри тела метода.
6. Не пиши лишнего: коротко, информативно, точно. Развёрнутый <remarks> оправдан только там, где этого требуют правила ниже (DA-классы: таблица, операция, колонки, bind-параметры) — это не «лишнее», а осознанное исключение.
7. Язык вывода — русский.
8. Вставляй чистые /// прямо в .cs через Edit; не оборачивай код в markdown-блоки (fenced-заборы или csharp-обёртки) и не возвращай его отдельным текстовым блоком.
9. Если комментарий у члена уже есть — не дублируй его, только добавь недостающие теги.
10. Если тип/файл уже задокументирован — верни без изменений. Операционный критерий — шаг 4 алгоритма (/// <summary> над объявлением типа); ориентир «хорошо документирован» — > 90 % публичных членов с doc. Флаг --force отменяет пропуск.

Когда срабатывать

Пользователь явно просит добавить XML-doc комментарии в C#-код. Триггерные глаголы: «задокументируй», «добавь summary», «оформи XML-doc», «добавь ///», «doc-cs».

Общий алгоритм

1. Уточни область. Если аргумент не задан — спроси, что документировать: файл, класс, метод или папку (src/**/*.cs).
2. Формат документации — только inline. Содержимое документации doc-cs пишет исключительно как /// в .cs-файлах; внешняя Markdown-документация — задача doc-md, не дублируй её здесь. Правка .csproj (шаг 8) — не документация, а вспомогательное build-действие (включение генерации XML) и единственное исключение из правила «только .cs».
3. Прочитай целевые файлы через Read/Glob. Если файлов много — распараллель обработку субагентами, не более 10 одновременно (см. «Обработка больших проектов (параллелизм ≤ 10)»).
4. Пропусти уже задокументированные файлы. Если у класса в файле уже есть XML-doc (/// <summary> непосредственно над объявлением class) — пропусти весь .cs и сообщи («пропущен: класс уже задокументирован»). Файлы с несколькими top-level классами пропускай, только если задокументированы все. Флаг --force отменяет пропуск. Это делает повторные прогоны идемпотентными и не тратит субагентов на готовые файлы.
5. Для каждого публичного типа и члена оставшихся файлов сгенерируй XML-doc по правилам.
6. Не трогай уже задокументированные члены с непустым <summary> — только добавь недостающие теги (<param>, <returns>, <exception>).
7. Сохрани через Edit — вставка /// в исходный .cs.
8. Включи генерацию XML-документации. Для каждого затронутого проекта добавь <GenerateDocumentationFile>true</GenerateDocumentationFile> в его .csproj — детали в секции «Включение GenerateDocumentationFile в .csproj».

Правила содержания

Чего НЕ делать

• Не дублируй имя метода/класса в <summary>. «Метод для вставки записи» — мусор; имя уже это сказало.
• Не пиши шаблонные <param> вроде «Идентификатор». Объясняй семантику: «Первичный ключ записи DICT.SV_ITEM (SV_ID).»
• Не выдумывай исключения, которых код не бросает. <exception> — только если видишь throw или это очевидно из ADO.NET-контекста (OracleException при ExecuteNonQuery, InvalidOperationException при закрытом соединении).
• Не используй ALL-CAPS MUST/NEVER в тексте документации.
• Не используй <list type="table"> в XML-doc (DocFX поддерживает только 2 колонки). Если нужна табличная подача — это формат doc-md.

Что делать

• <summary> — одно предложение: «что делает и зачем». Шире — в <remarks>.
• <param> — семантика, не тип.
• <returns> — что вернётся, когда null/-1/пустая коллекция.
• <exception> — причина, не только тип.
• Для override/реализаций — <inheritdoc/> (для NuGet ставить явно; Visual Studio автонаследует в IDE, но НЕ в выходной XML).
• Для async — упомяни Task/ValueTask и CancellationToken.
• В <remarks> для DA-классов всегда: имя таблицы Oracle, тип операции, затронутые колонки, bind-параметры.

Полный набор тегов

См. references/xml-tags-ru.md. Базовый набор: <summary>, <remarks>, <param>, <paramref>, <returns>, <exception>, <value>, <typeparam>, <typeparamref>, <example>, <code>, <c>, <see>, <seealso>, <inheritdoc>, <include>, <para>, <br/>, <list type="bullet|number">, <a>. Экранирование: < → <, > → >.

Пример: SvItemDao.Insert (как должно быть сгенерировано)

/// <summary>
/// Вставляет новую запись справочника «Уровни доступа» в таблицу
/// <c>DICT.SV_ITEM</c>.
/// </summary>
/// <remarks>
/// Выполняет одиночный <c>INSERT</c> со всеми 14 колонками, включая
/// мультиязычные наименования <c>SV_NAME00</c>..<c>SV_NAME05</c> и
/// аудит-поля (<c>SV_USER</c>, <c>SV_DATEENTER</c>). Поле
/// <c>SV_PREVIOUSID</c> используется для версионирования: при правке
/// существующей записи в него передаётся <see cref="SvItem.Id"/>
/// предыдущей версии, иначе <c>null</c>. <c>SV_RECORDSTATUS</c>
/// отвечает за soft-delete: <c>1</c> — активна, <c>0</c> — архивная.
/// Bind-параметры: <c>:p_ID</c>, <c>:p_GUID</c>, <c>:p_PREVID</c>,
/// <c>:p_RS</c>, <c>:p_USER</c>, <c>:p_DATE</c>, <c>:p_COMMENT</c>,
/// <c>:p_N00</c>..<c>:p_N05</c>, <c>:p_SYS</c>.
/// </remarks>
/// <param name="m">
/// DTO-модель новой записи; поля <see cref="SvItem.Guid"/> и
/// <see cref="SvItem.System"/> обязательны, остальные допускают
/// <see langword="null"/>.
/// </param>
/// <returns>
/// Количество вставленных строк (ожидается 1). При нарушении
/// уникальности <c>SV_GUID</c> метод выбрасывает исключение,
/// а не возвращает 0.
/// </returns>
/// <exception cref="Oracle.ManagedDataAccess.Client.OracleException">
/// Возникает при нарушении ограничений целостности (например,
/// дублирующий <c>SV_GUID</c>) или при недоступности схемы <c>DICT</c>.
/// </exception>
/// <seealso cref="Update(SvItem)"/>
/// <seealso cref="GetById(long)"/>
public long Insert(SvItem m) { /* … */ }

Обработка больших проектов (параллелизм ≤ 10)

Опциональный режим — для одного файла работай напрямую. При большом числе .cs-файлов:

1. Сначала отсей уже задокументированные файлы (см. шаг 4 общего алгоритма) — в главной сессии, до диспетча, чтобы не тратить субагентов на готовое. Затем раздели оставшиеся файлы на группы и обрабатывай волнами не более 10 параллельных субагентов (Task): до 10 вызовов Task в одном сообщении, дождись завершения волны, затем следующую.
2. Каждому субагенту в промпте передай системный промпт (роль) из секции выше, пути к его .cs-файлам и к references/ (style-rules-ru.md, xml-tags-ru.md, examples-ru.md) — он обязан прочитать их перед генерацией, иначе стиль <summary> и набор тегов разъедутся между агентами.
3. Каждый субагент правит только свои файлы (Edit для inline ///) — файлы не пересекаются, конфликтов записи нет.

Включение GenerateDocumentationFile в .csproj

Активный шаг после документирования — чтобы добавленные /// попадали в выходной XML-файл.

1. Скоуп. Правь только .csproj проектов, чьи .cs реально обработаны (ближайший .csproj вверх по дереву). Не обходи весь репозиторий глобом **/*.csproj. Если есть Directory.Build.props, задающий это свойство сразу на все проекты, — внеси правку там один раз вместо per-project.
2. Куда. В безусловный <PropertyGroup> (без атрибута Condition; в SDK-style проекте — тот, где <TargetFramework>).
3. Идемпотентность. Тега нет → добавь <GenerateDocumentationFile>true</GenerateDocumentationFile>; уже true → ничего не делай; стоит false → не меняй молча, сообщи пользователю.
4. CS1591. true включает предупреждение CS1591 на каждый недокументированный public-член, а doc-cs покрывает не всё (приватные, пропущенные файлы). Поэтому включай свойство после прохода документирования. Если в проекте включён TreatWarningsAsErrors — предупреди пользователя (билд покраснеет до полного покрытия) и предложи, но не добавляй молча, <NoWarn>$(NoWarn);CS1591</NoWarn>.

Post-process (опционально, напомнить пользователю)

• DocFX для HTML-сайта (не задача этого skill'а).

Когда отказаться

• Просят внешние .md-файлы / «сгенерируй .md для класса» — это doc-md.
• Просят «сгенерировать database.md» / «опиши схему БД» — это doc-db.