| 1 | # Контракт XML-доков для `IdeCommands` и ProtocolDocGen |
| 2 | |
| 3 | Инструмент `tools/CascadeIDE.ProtocolDocGen` **не** разбирает полный набор стандартных тегов C# XML documentation (`<returns>`, `<param>`, `<remarks>`, …). |
| 4 | |
| 5 | ## Что реально читается |
| 6 | |
| 7 | - **Только текст внутри `<summary>…</summary>`** у каждого `public const string` в частичном классе `IdeCommands` (после склейки `IdeCommands.cs` + `IdeCommands.*.cs`). |
| 8 | - Строки `///` вне блока summary для константы **игнорируются** парсером (в т.ч. отдельная строка `/// <returns>json</returns>` **не попадёт** в контракт и не заменит `returns:` в summary). |
| 9 | |
| 10 | ## Мини-язык внутри summary |
| 11 | |
| 12 | Для линта и генерации (`IdeCommandsContract`, `IdeCommandsArgs`, таблица в `MCP-PROTOCOL.md`) в **одной** строке summary используются договорённые фрагменты: |
| 13 | |
| 14 | | Фрагмент | Назначение | |
| 15 | |----------|------------| |
| 16 | | `args: …` | Схема аргументов для `IdeCommandsArgs` (см. грамматику в `Program.cs`, `IdeCommandArgsParser`). | |
| 17 | | `returns: json` \| `text` \| `none` | Вид возвращаемого значения для контракта и подсказок. | |
| 18 | | `example: {…}` | Пример JSON args (обязателен, если в summary есть `args:`). | |
| 19 | |
| 20 | Пробелы нормализуются; вложенные XML-теги в summary вычищаются, кроме подстановки `` ` `` для `<c>…</c>`. |
| 21 | |
| 22 | ## Почему не `<returns>` |
| 23 | |
| 24 | Отдельный тег `/// <returns>` был бы правильнее для IDE и компилятора, но потребовал бы **другой парсер** (многострочные теги, порядок относительно `const`, слияние с summary). Текущая схема — один поток текста на команду, предсказуемый линт и простая генерация. |
| 25 | |
| 26 | Если понадобится: можно **расширить** `IdeCommandsParser`, чтобы он подмешивал текст из `<returns>` в нормализованный summary (или заполнял поле возврата отдельно), не ломая существующий мини-язык. |
| 27 | |
| 28 | ## См. также |
| 29 | |
| 30 | - Реализация: `tools/CascadeIDE.ProtocolDocGen/Program.cs` (`IdeCommandsParser`, `IdeCommandsLint`, эмиттеры). |
| 31 | - Чертёж реестра: [ide-command-registry-v1.md](../design/ide-command-registry-v1.md). |
| 32 | - Целевое состояние (каноничные XML-теги, миграция, в т.ч. **вариант B:** стандартные теги + свои для машинного контракта): [ADR 0018](../adr/0018-ide-commands-canonical-xml-documentation.md). |
| 33 | |