XML-док

Пример

// <doc>
 //   <summary>Форматированный вывод: {P1},{P2} или {Имя}.</summary>   ✦
 //   <param i="1" name="Template" type="String">Шаблон</param>   ➤
 //   <param i="2" name="Params"   type="Array|Structure">Массив/Структура значений</param>   ➤
 //   <returns>String — итоговая строка</returns>   ⬅
 //   <complexity cc="3"/>
 //   <example>
 //     // A1sS.FormatPlaceholders("Hi {P1}", Новый Массив("Ann"));
 //     // A1sS.FormatPlaceholders("Привет, {Имя}", Новый Структура("Имя", "Боб"));
 //   </example>
 // </doc>

Зачем XML-док вместо «типового» блока 1С

• Машиночитаемо. Теги <param/returns/locals/complexity/example> легко парсятся линтером/генераторами.
• Синхронизация с кодом. Числовой индекс i="1..n", имя и тип параметра уменьшают риск «скопипастили и забыли поменять».
• Единый стиль RU/EN. Полезно для автогенерации документации и подсказок в IDE/чат-ассистентах.
• Сложность. <complexity cc="k"/> позволяет хранить фактическую цикломатику рядом с функцией.
• Примеры. Короткий пример в <example>, длинные сценарии — в отдельном регионе #Region examples_*.

Сравнение

// Типовой «вольный» блок 1С:
// Функция: Форматирование строки
// Параметры: Template (Строка), Params (Массив/Структура)
// Возврат: Строка

// A1sCode XML-док (структурировано):
// <doc>
//   <summary>Форматированный вывод: {P1},{P2} или {Имя}.</summary>   ✦
//   <param i="1" name="Template" type="String">Шаблон</param>   ➤
//   <param i="2" name="Params"   type="Array|Structure">Массив/Структура</param>   ➤
//   <returns>String — итоговая строка</returns>   ⬅
//   <complexity cc="3"/>
// </doc>

Итог: типовой блок удобен глазами, но непредсказуем для машин; XML-док A1sCode одинаково хорошо читает и человек, и инструмент.

Правила

• Каждая строка начинается с // , внутренний отступ — 2 пробела.
• Маркеры: ✦ — только у <summary>; ➤ — у <param>; ⬅ — у <returns>.
• Маркеры в конце строки через 3 пробела. Для <doc>/</doc> — без маркера.