Документирующие комментарии
«1С:Шина» поддерживает документирование собственного кода разработчика с помощью оформленных по определенным правилам комментариев. Эту информацию «1С:Шина» использует для предоставления контекстной подсказки в среде разработки аналогично отображению подсказок для системных типов и методов.
Документирование кода в модулях
В отличие от обычных комментариев, которые используются для пояснения логики выполняемого кода, документирующие комментарии имеют строгий синтаксис и располагаются непосредственно перед объявлением элемента кода (структуры, перечисления, метода, константы и т. д.). В «1С:Шине» документирующий комментарий начинается с символов ///.
Вы можете добавить документирующий комментарий двумя способами:
-
Установите курсор на пустую строку перед документируемым элементом, введите
///и нажмите клавишу Ввод. -
Установите курсор на пустую строку перед документируемым элементом и вызовите контекстную подсказку с помощью клавиш Ctrl+Пробел. Во всплывающем меню выберите Документирующий комментарий.
«1С:Шина» сгенерирует шаблон описания элемента. Для структур, полей, перечислений и констант сгенерируется стандартный комментарий: /// Документирующий комментарий. Для метода дополнительно указываются параметры и возвращаемое значение (при наличии).
Для описания синтаксиса элемента вы можете включить в комментарий следующие теги:
@параметр Имя— описание параметра,@возвращает— описание возвращаемого значения,@выбрасывает ТипИсключения— описание выбрасываемого исключения,@см— дополнительная информация для пользователя.
/// Вычисляет площадь прямоугольника.
///
/// @параметр Длина - Длина прямоугольника.
/// @параметр Ширина - Ширина прямоугольника.
///
/// @возвращает Площадь прямоугольника.
/// @выбрасывает ИсключениеНедопустимыйАргумент - если аргументы отрицательные.
метод ВычислитьПлощадь(Длина: Число, Ширина: Число): Число
если Длина < 0 или Ширина < 0
выбросить новый ИсключениеНедопустимыйАргумент("Стороны прямоугольника не могут быть отрицательными")
;
возврат Длина * Ширина
;
Документирующий комментарий показывается в контекстной подсказке при наборе кода и во всплывающей подсказке при наведении мыши на элемент.
Документирование элементов проекта
«1С:Шина» поддерживает создание документирующих комментариев для элементов проекта и их составных частей (реквизитов, полей, параметров и т. п.).
Для добавления комментария к элементу, откройте его панель свойств и раскройте свойство Документирующий комментарий. Откроется редактор кода для удобного ввода и форматирования комментария в формате Markdown.
В редакторе доступны следующие возможности:
- изменение вида начертания шрифта,
- создание заголовков разного уровня (от H1 до H6),
- создание маркированных и нумерованных списков,
- добавление цитат и ссылок,
- вставка изображений,
- предварительный просмотр комментария.
Введенный комментарий сохраняется в YAML-файле элемента.
Пример YAML-файла ключа доступа «КлючДоступаСотрудника»
## Выдаваемый ключ доступа сотрудника организации.
##
## Содержит два параметра:
##
## * **Регион** — регион сотрудника,
## * **СпособПодключения** — способ подключения сотрудника (локально или удаленно).
ВидЭлемента: КлючДоступа
ОбластьВидимости: ВПодсистеме
Ид: 929e9fab-faf0-4062-9a9d-ae93d7881b82
Имя: КлючДоступаСотрудника
РучнаяВыдача: Истина
Параметры:
-
Ид: 3b5b1025-9c47-4735-b2b9-57682c95b004
Имя: СпособПодключения
Тип: Строка
-
Ид: d3c5cf40-b4ea-4ba1-9064-6de029e1335b
Имя: Регион
Тип: Строка
Документирующий комментарий показывается в контекстной подсказке при вводе кода и написании запросов к таблицам элементов проекта, а также во всплывающей подсказке при наведении мыши на элемент в среде разработки (навигаторе проекта и панели свойств).
