Прикладной код

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

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

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

Операция

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

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

Функция

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

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

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

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

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