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

Материал из Энциклопедия о программировании
Перейти к: навигация, поиск

Документирующие комментарии (doc comments, documentation comments) — разновидность (подвид) многострочных комментариев; специальный вид комментариев оформленных особым образом и применяющихся к определённому объекту программы для использования каким-либо конкретным генератором документации. Во многих популярных языках программирования имеются подобные документирующие комментарии. По сути они являются обычными многострочными комментариями с некоторыми внутренними особенностями.

От того, какой генератор документации применяется, зависит синтаксис конструкций, используемых в документирующих комментариях.

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

Документирующие комментарии, как правило, оформляются как многострочные комментарии в стиле языка Си. В каждом случае комментарий должен находиться перед документируемым элементом. Первым символом в начале каждой строки документирующего комментария должен быть *, после которого следует пробел. Часто блоки разделяются пустыми строками. Так же при открытии документирующего комментария используется два знака * после слэша.

Основной отличительной особенностью документирующих комментариев от обычных многострочных является наличие "параметров". Параметры могут быть самыми разными, перед названием параметра пишется знак "собаки" (@). Название параметра от его значения разделяет пробел.

Содержание

Примеры

Этот раздел также можно назвать, или альтернативные заголовки раздела:
  • Примеры документирующих комментариев в Си-подобных языках программирования

PHP

Пример документирующего комментария на языке PHP:

/**
 * Имя или краткое описание объекта
 * 
 * Развернутое описание
 * 
 * @имя_дескриптора значение
 * @return тип_данных
 */

Java

Пример документирующего комментария к функции в программе на Java, предназначенного для использования Javadoc:

/**
 * Проверяет, допустимый ли ход.
 * Например, чтобы задать ход e2-e4, напишите isValidMove(5,2,5,4);
 * @author John Doe
 * @param theFromFile Вертикаль, на которой находится фигура (1=a, 8=h)
 * @param theFromRank Горизонталь, на которой находится фигура (1...8)
 * @param theToFile   Вертикаль клетки, на которую выполняется ход (1=a, 8=h)
 * @param theToRank   Горизонталь клетки, на которую выполняется ход (1...8)
 * @return true, если ход допустим, и false, если недопустим
 */
boolean isValidMove(int theFromFile, int theFromRank, int theToFile, int theToRank) {
	// …
}

C#

Однострочные документирующие комментарии в C Sharp:

/// <summary>
/// This is the single line version of the doc comment
/// </summary>
static void Example() {
	// …
}

Многострочные документирующие комментарии в C#:

/** <summary>
 * This is the multi-line version
 * </summary> */
static void Example() {
	// …
}