Избыточное наличие описания параметра в комментарии к процедуре (функции), отсутствующего в сигнатуре вызова

Секция Параметры описывает параметры процедуры (функции). Если их нет, секция пропускается. Предваряется строкой "Параметры:", затем с новой строки размещаются описания всех параметров.

Описание параметра начинается с новой строки, далее имя параметра, затем дефис и список типов (*), далее дефис и текстовое описание параметра. В описании параметра следует приводить сведения, дающие дополнительную информацию о типе, поясняющие назначение параметра, а также может приводиться наглядный пример с ожидаемым значением параметра.

Например, неправильно:

// Строка - Строка - строка, содержащая электронные адреса.
// МассивПеренаправленныхЗадач - Массив - массив перенаправленных задач.
// ЗадачаСсылка  - ЗадачаСсылка.ЗадачаИсполнителя - задача.

Правильно:

// Адреса - Строка - содержит электронные адреса, разделенные запятой. Например, "support@mycorp.ru, v8@localdomain".
// ПеренаправленныеЗадачи - Массив – задачи (ЗадачаСсылка.ЗадачаИсполнителя) перенаправленные другому исполнителю.
// ЗадачаИсполнителя - ЗадачаСсылка.ЗадачаИсполнителя – проверяемая задача исполнителя.

(*) Примечание: под «списком типов» подразумеваются имена типов, разделенные запятыми. Имя типа может быть простым (в одно слово) или составным - в два слова, разделенных точкой.

Например: Строка, Структура, Произвольный, СправочникСсылка.Сотрудники.

Кроме того, не следует использовать в качестве типов значений несуществующие в платформе типы. В случае если в качестве типа используется более семи типов, объединенных общим критерием, следует описывать в параметре несколько наиболее распространенных типов, а в описании параметра указывать этот критерий. Например, неправильно:

// КоллекцияСтрок - КоллекцияЗначений – коллекция для сравнения;

Правильно:

// КоллекцияСтрок – ТаблицаЗначений, Массив, СписокЗначений – Элемент для
//          сравнения. Также в качестве значения параметра могут быть указаны
//          любые другие коллекции значений, для которых доступен обход посредством оператора
//          Для каждого … Из … Цикл;

Для параметров типа Структура и ТаблицаЗначений также задается описание их свойств и колонок, которые начинаются с новой строки и предваряются символом *.

Например:

// Параметры:
//   СтатусыСерий - ТаблицаЗначений - таблица с колонками:
//     * Серия - СправочникСсылка.СерииНоменклатуры - если серия указана и она может
//               использоваться с новым значением номенклатуры на указанном складе,
//               то возвращается переданное значение; если нет - пустая ссылка
//     * СтатусУказанияСерий - Число - если серии указываются в ТЧ "Товары", то
//               возвращается рассчитанный статус, если для переданной
//               номенклатуры/склада серии не используется - возвращается 0
//               иначе возвращается переданный статус.
//   ПараметрыУказанияСерий - Структура - см. НоменклатураКлиентСервер.ПараметрыУказанияСерий

Аналогично для параметров типа Массив:

// Параметры:
//  СведенияОбОбновлении  - Массив - cодержит структуры со свойствами:
//     * КодАдресногоОбъекта - Строка - код адресного объекта.
//     * Наименование        - Строка - наименование адресного объекта.
//     * Индекс              - Строка - индекс адресного объекта.
//     * ОбновлениеДоступно  - Булево - признак наличия обновления.

В описании массивов, структур и таблиц значений могут быть вложенные описания, при этом перед именами вложенных свойств число звездочек увеличивается: для первого уровня вложенности 2 звездочки, для второго 3 и т.д.

// Параметры:
//  СведенияОбОбновлении  - Массив - cодержит структуры со свойствами:
//     * КодАдресногоОбъекта - Структура - код адресного объекта.
//        ** КодРегиона             - Число - код региона (длина - 2).
//        ** КодНаселенногоПункта   - Число - код населенного пункта (длина - 3).
//        ** КодУлицы               - Число - код улицы (длина - 4).
//     * Наименование        - Строка    - наименование адресного объекта.
//     * ОбновлениеДоступно  - Булево    - признак наличия обновления.

См. также

Экранирование кода

// sonar:DocumentationExcessParametersInParametersSection:off
// sonar:DocumentationExcessParametersInParametersSection:on