Перейти к содержанию

ADR 0018: Каноничные XML-доки для IdeCommands и ProtocolDocGen

Статус: Accepted (частично: ProtocolDocGen + generated summaries; полный XML на IdeCommands — по миграции)
Дата: 2026-04-05

Связанные ADR

ADR Роль
0013 единый реестр command_id
0008 контракты MCP

Вне ADR

Документ Роль
ide-commands-protocol-docgen-contract.md текущий контракт парсера

Контекст

Реестр команд IdeCommands (частичный класс, Services/IdeCommands.cs + Services/IdeCommands.*.cs) снабжается XML-комментариями; tools/CascadeIDE.ProtocolDocGen генерирует IdeCommandsDoc, IdeCommandsArgs, IdeCommandsContract, фрагмент MCP-PROTOCOL.md и прогоняет линт контракта.

Сейчас машиночитаемые части контракта (returns:, args:, example:) вложены в текст <summary> — см. ide-commands-protocol-docgen-contract.md. Это упростило первый построчный парсер, но:

  • для открытого репозитория и новых контрибьюторов привычнее стандартная структура C# XML documentation (<summary>, <param>, <returns>, <example> / <code>);
  • IDE и привычные инструменты ожидают человеческое описание в summary, а тип возврата и параметры — в отведённых тегах.

Решение (целевое состояние)

Базовая идея: опираться на привычные теги (<summary>, при необходимости <param> / <returns> для человека), а машинный контракт для ProtocolDocGen выражать отдельно — либо внутри стандартных тегов по соглашению, либо через свои (расширенные) XML-теги, не подменяя ими базовые.

Вариант A — только стандартные теги + соглашения

  1. <summary> — краткое описание для человека; машинные части при необходимости в <returns> и <param> по явным правилам (см. ниже вариант B для смешения).

  2. <param name="…"> — человекочитаемое описание; для схемы IdeCommandsArgs — соглашение (первая строка — мини-грамматика name:type, остальное — текст) или одна строка схемы в <remarks>.

  3. <example> + <code language="json"> — пример для линта.

Вариант B — стандартные теги + свои теги (предпочтительно обсуждать)

Не «ломать» семантику стандартных тегов жёсткой машинной строкой, а добавить элементы с фиксированными именами под Cascade/ProtocolDocGen, например (имена на этапе Accepted зафиксировать в dev-доке):

  • отдельный тег для схемы аргументов (одна строка в прежней грамматике или структурированный XML внутри);
  • отдельный тег для вида возврата контракта (json / text / none);
  • при необходимости отдельный тег для примера JSON (если не хочется дублировать логику с <example>).

Почему это естественно: компилятор C# сохраняет нестандартные теги в выходном XML документации; IDE по умолчанию показывает в Quick Info в основном <summary> / <param> / <returns> — кастомные теги не «ломают» подсказки, а ProtocolDocGen читает полный блок и извлекает и стандартные, и свои элементы. Так делают многие SDK и генераторы доков (Sandcastle/DocFX — свои теги; у проекта — свой контролируемый набор).

Имена тегов: лучше стабильный префикс или неймспейсоподобная схема (cascadeArgs, cascadeReturns — или одно согласованное имя блока), чтобы не пересечься с будущими расширениями инструментов.

Общее для обоих вариантов

  1. Реализация парсера: разбор XML-документа к символу (предпочтительно Roslyn + полный XML комментария к const); склейка IdeCommands*.cs как сейчас.

  2. Миграция: перевести IdeCommands.*.cs на выбранный шаблон; при необходимости короткая совместимость линта со старым форматом в <summary> или один крупный коммит.

Выбор A vs B

Оставить на финализацию ADR: если B — меньше компромиссов в формулировках стандартных тегов и яснее граница «человек / машина»; цена — документировать список кастомных тегов и один раз встроить их в парсер.

Последствия

  • Плюсы: ближе к экосистеме C#, проще onboarding; вариант B дополнительно отделяет «прозу для людей» от «полей для генератора» без наслоения грамматики на <summary>.
  • Минусы: разовая стоимость рефакторинга парсера и комментариев; для A — жёсткое соглашение по тексту внутри <param> / remarks; для B — каталог кастомных тегов и поддержка в ProtocolDocGen (зато контракт явный).
  • Документация: обновить ide-commands-protocol-docgen-contract.md после принятия реализации (или в том же PR, что и парсер).

Отклонённые альтернативы

  • Оставить навсегда только мини-язык в <summary> — отклонено как долгосрочная цель для открытого репозитория: работает, но хуже для контрибьюторов и стандартных ожиданий.

Статус

До перехода на Accepted — после выбора варианта A или B, точных имён тегов (в т.ч. кастомных), соглашения по args и реализации парсера (и по желанию пилот на одном файле IdeCommands.*.cs).