Документирующие комментарии

«1С:Предприятие.Элемент Скрипт» поддерживает документирование собственного кода разработчика с помощью оформленных по определенным правилам комментариев. Эту информацию «1С:Предприятие.Элемент Скрипт» использует для предоставления контекстной подсказки в среде разработки аналогично отображению подсказок для типов и методов языка «1С:Элемент».

Отображение документирующего комментария в контекстной подсказке

Документирование кода

В отличие от обычных комментариев, которые используются для пояснения логики выполняемого кода, документирующие комментарии имеют строгий синтаксис и располагаются непосредственно перед объявлением элемента кода (структуры, перечисления, метода, константы и т. д.). В «1С:Предприятие.Элементе Скрипте» документирующий комментарий начинается с символов ///.

Вы можете добавить документирующий комментарий двумя способами:

Установите курсор на пустую строку перед документируемым элементом, введите /// и нажмите клавишу Ввод.
Установите курсор на пустую строку перед документируемым элементом и вызовите контекстную подсказку с помощью клавиш Ctrl+Пробел. Во всплывающем меню выберите Документирующий комментарий.

«1С:Предприятие.Элемент Скрипт» сгенерирует шаблон описания элемента. Для структур, полей, перечислений и констант сгенерируется стандартный комментарий: /// Документирующий комментарий. Для метода дополнительно указываются параметры и возвращаемое значение (при наличии).

Для описания синтаксиса элемента вы можете включить в комментарий следующие теги:

@параметр Имя — описание параметра,
@возвращает — описание возвращаемого значения,
@выбрасывает ТипИсключения — описание выбрасываемого исключения,
@см — дополнительная информация для пользователя.

Пример документирующего комментария для описания метода
/// Вычисляет площадь прямоугольника.
/// 
/// @параметр Длина - Длина прямоугольника.
/// @параметр Ширина - Ширина прямоугольника.
/// 
/// @возвращает Площадь прямоугольника.
/// @выбрасывает ИсключениеНедопустимыйАргумент - если аргументы отрицательные.
метод ВычислитьПлощадь(Длина: Число, Ширина: Число): Число
    если Длина < 0 или Ширина < 0
        выбросить новый ИсключениеНедопустимыйАргумент("Стороны прямоугольника не могут быть отрицательными")
    ;
    возврат Длина * Ширина
;

Документирующий комментарий показывается в контекстной подсказке при наборе кода и во всплывающей подсказке при наведении мыши на элемент.

Отображение документирующего комментария во всплывающей подсказке

Документирование кода​

Документирование кода