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

Общая информация

Документирующий комментарий — это комментарий к собственной процедуре или функции, написанный по определенным правилам.

В комментарии перечисляются параметры, их типы и назначение, тип и назначение возвращаемого значения.

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

• Эта информация отображается в панели Синтакс-помощник.

  

• Эта информация показывается во всплывающей подсказке при наведении мыши на вызов метода.

  

• Эта информация используется контекстной подсказкой при вводе параметров процедуры или функции.

  

• Если параметр или возвращаемое значение имеют тип Структура, ТаблицаЗначений или ДеревоЗначений, то с помощью документирующего комментария можно описать имена и типы ключей и колонок. Тогда контекстная подсказка будет показывать эти данные при обращении через точку от параметра или от возвращаемого значения.
• Тип значения параметра можно описать как ссылку на функцию, которая возвращает это значение. Тогда 1C:EDT позволяет быстро перейти к объявлению этой функции.
• Типы, указанные в документирующих комментариях, 1C:EDT может использовать для проверок в режиме строгой типизации.

Правила написания документирующих комментариев

Панель «Bsl Документирующий комментарий»

В поставку EDT входит плагин 1C:Code style V8. Он содержит эту панель. Она в перспективе 1C:Enterprise.

Показывает структуру документирующего комментария, что позволяет правильно форматировать сложные комментарии. Позволяет исправить ошибки, допущенные при написании комментария.

Описание панели можно посмотреть в документации плагина 1C:Code style V8.

Открыть панель Окно > Показать панель > Другое... > 1С:Стандарты разработки V8 > Bsl Документирующий комментарий

Продолжить многострочный комментарий

Часто бывает так, что комментарии длинные и не помещаются на одной строке. Чтобы быстро продолжить комментарий на следующей строке, можно нажать Shift+Ввод.

Автоматически будет добавлена новая строка, которая уже содержит символ комментария в начале.

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

Чтобы вставить шаблон документирующего комментария, выполните следующие действия:

1. Установите курсор в пустую строку, непосредственно перед объявлением метода или на само объявление;
2. Нажмите Источник Генерировать комментарии к методу в контекстном меню.

Эта команда может не только вставить новый комментарий, но и улучшить существующий.

Например, если в объявлении метода появился новый параметр, эта команда добавит его в комментарий.

Если комментарий написан не по правилам, она дополнит его и отформатирует его стандартным образом.

Ошибки типизации

Документирующие комментарии, сами по себе, не приведут к тому, что 1C:EDT начнет обнаруживать ошибки типизации. Помимо того, что типы параметров и возвращаемых значений должны быть описаны в документирующих комментариях, нужно включить строгую типизацию во всем прикладном решении или в некоторых его объектах или в некоторых модулях.

В поставку 1C:EDT входит плагин 1C:Code style V8. Он позволяет включать строгую типизацию.

Пока не включена строгая типизация, 1C:EDT не проверяет соответствие указанных и используемых типов. После включения строгой типизации 1C:EDT будет сообщать обо всех подобных ошибках. Например, если вы указали, что у параметра тип Строка и передали в него значение типа Число.

Строгая типизация включается путем добавления аннотации //@strict-types в начало модулей. Чтобы включить строгую типизацию:

1. В панели Навигатор выделите:
   1. Проект или конфигурацию, если хотите включить во всем приложении;
   2. Объект конфигурации, если хотите включить только в его модулях;
   3. Модуль, если хотите включить только в этом модуле;
2. Нажмите Включить строгую типизацию (@strict-types) в модулях в контекстном меню.