Документировать функцию/операцию

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

Операция

При создании или редактировании операции можно указать:

• описание операции;
• @author — ФИО автора операции;
• @editor — ФИО сотрудника, который редактирует операцию.
  

Функция

При создании или редактировании функции можно указать:

• описание функции;
• @param — принимаемые аргументы;
• @return — возвращаемые параметры;
• @author — ФИО автора операции;
• @editor — ФИО сотрудника, который редактирует операцию;
• код функции и дополнительные комментарии.
  

Ошибки при документировании функций/операций

В редакторе прикладного кода важно соблюдать формат документирования. Для создаваемых функций/операций отсутствие комментариев является ошибкой. В случае их редактирования будет выведено предупреждение.

• «Необходимо документировать функцию/операцию комментариями в формате JSDoc» — отсутствие блока комментария;
• «Необходимо описание функции/операции» — перед тегами в комментарии не найдены корректные символы;
• «Аргумент не документирован» — для одного из параметров не найден тег @param с корректным указанием типа и имени аргумента;
• «Аргумент не указан в объявлении функции» — имя аргумента в одном из тегов @param не совпадает с именем аргумента принимаемого функцией;
• «Дублирующееся описание параметра» — дублирование описания для аргумента. Имена аргументов должны быть уникальны;
• «Необходим тег @return с описанием типа возвращаемого функцией значения» — отсутствует тег @return с описанием типа возвращаемого функцией значения;
• «Функция должна быть объявлена» — в коде отсутствует элемент, который объявляет функцию;
• «Объявление функции должно быть единственным блоком» — в коде должен быть только один элемент, который объявляет функцию;
• «Функция должна быть объявлена с тем же именем» — имя функции в объявлении отличается от имени в заголовке редактора.