Комментарии в yaml

Где пояснение в описании элемента переживает визуальный редактор, как его писать и что за этим следит.

Среда разработки 1С:Элемент хранит описание элемента моделью. Когда вы правите файл в визуальном редакторе, она пишет yaml заново из этой модели. Из комментариев в модели остаются только документирующие: строки ## там, где у модели есть поле для описания. Обычный # и строки ## не на своём месте пропадают при первой такой правке.

Где у пояснения есть место

Первые строки файла. Здесь описывают сам элемент: компонент интерфейса, общий модуль, HTTP-сервис, справочник, перечисление.
Первые строки узла-компонента, перед Тип:. Так описывают и Наследует:, и вложенные узлы.
Первая строка элемента списка после -, если модель описывает такие записи. Это свойства компонента в Свойства:, шаблоны адресов HTTP-сервиса в ШаблоныUrl:, реквизиты и табличные части справочника в Реквизиты: и ТабличныеЧасти:.

Места нет у стандартных реквизитов справочника, которые выбираются по имени (Код, Наименование), у элементов Методы: шаблона адреса и у отдельного свойства узла. У экземпляра компонента проекта или библиотеки в списке комментарий вредит: с ним сервер не применяет проект, потому что сборка метаданных экземпляра падает. Пояснение к такому узлу пишут в комментарий группы, в которой он стоит.

Как писать

Маркер – ## , текст – Markdown: жирный и курсив, заголовки, цитата, вложенные списки, ссылка, картинка. Каждая строка ## выводится своей строкой, пустая строка ## делит абзацы.

## Панель заказа: получатель и состав заказа.
ВидЭлемента: КомпонентИнтерфейса
Ид: 6f0b6a44-0000-4000-8000-000000000101
Имя: ПанельЗаказа
Наследует:
    ## Форма заказа в две колонки.
    Тип: ФормаОбъекта<Заказы.Объект>
    Содержимое:
        -
            ## Подсказка над полями ввода.
            Тип: Надпись
            Имя: Подсказка

В модуле .xbsl описание над объявлением среда разработки читает по строкам ///. Блок // и блок /* ... */ на том же месте она в подсказке не показывает.

Что за этим следит

yaml/plain-comment находит каждый # в описании элемента. Если место для пояснения рядом, автоисправление меняет маркер или переносит блок внутрь узла.
yaml/doc-comment-misplaced находит блок ## там, где среда разработки его не читает.
comment/doc-marker находит в модуле блок // прямо над объявлением и меняет маркер на ///.

Все три правила выключены по умолчанию и включаются ключом --enable. В проекте, который писали до знакомства с визуальным редактором, они срабатывают почти на каждом узле.

Вставка фрагмента кладёт пояснения по тем же правилам. Так работают инструмент MCP meta_insert_fragment и операция insert-fragment команды xbsl form-edit. Комментарий над компонентом уходит внутрь узла строками ##. Пояснение без своего места остаётся как есть, и ответ называет его в заметках. Без данных технологии места неизвестны: пояснения остаются как вставлены, и ответ говорит об этом.

Свертка пояснений без своего места

Пояснение, рядом с которым нет своего места, переносит команда xbsl fold-comments. Это заметка к свойству компонента, к элементу списка без описания, к ключу элемента. Команда собирает такие блоки в описание ближайшего узла, у которого место есть, пунктом списка с именем предмета:

Наследует:
    ## * `Видимость`:
    ##   Группа видна всегда.
    Тип: Группа

Имя предмета стоит отдельной строкой, поэтому строки самого пояснения не меняются и их пары в словаре перевода остаются. Новым строкам с именами нужны свои пары, их покажет xbsl translate --gaps.

По умолчанию команда только показывает план и разницу, записывает ключ --write. Спорные переносы она предлагает, но не применяет: первый блок файла над ключом вне шапки (это может быть и описание элемента, и заметка к ключу), заголовок раздела, блок в файле локализации, элемент списка без имени, блок над списком. Применить и их – ключ --all. Заметку в конце файла команда не трогает: у нее нет хозяина.

Файл пишется, только если результат прошел проверку. Yaml разбирается в те же данные, все строки комментариев на месте, правила комментариев молчат, кроме блоков, оставленных намеренно, а второй проход не находит, что переносить. Метка порядка байтов и переводы строк файла сохраняются.

Агенту то же самое дает инструмент MCP meta_fold_comments. Он отвечает тем же отчетом, что --format json, и по умолчанию ничего не пишет: записывает dry_run=false, спорные переносы применяет take_proposed. Отчет называет каждый перенос, и по целому дереву в нем сотни килобайт; compact=true отвечает счетом, файлами с наибольшим числом переносов и переносами, на которые стоит взглянуть, а файлы, не прошедшие проверку, перечисляет все.