Документирующие комментарии
- Документирующие комментарии
-
Генератор документации — программа или пакет программ, позволяющая получать документацию, предназначенную для программистов (документация на API) и/или для конечных пользователей системы, по особым образом комментированному исходному коду и, в некоторых случаях, по исполняемым модулям (полученным на выходе компилятора).
Обычно, генератор анализирует исходный код программы, выделяя синтаксические конструкции, соответствующие значимым объектам программы (типам, классам и их членам/свойствам/методам, процедурам/функциям и т. п.). В ходе анализа также используется мета-информация об объектах программы, представленная в виде документирующих комментариев. На основе всей собранной информации формируется готовая документация, как правило, в одном из общепринятых форматов — HTMLHelp, RTF и других.
Документирующие комментарии
Документирующий комментарий — это особым образом оформленный комментарий к объекту программы, предназначенный для использования каким-либо конкретным генератором документации. От того, какой генератор документации применяется, зависит синтаксис конструкций, используемых в документирующих комментариях.
В документирующих комментариях может содержаться информация об авторе кода, описываться назначение объекта программы, смысл входных и выходных параметров — для функции/процедуры, примеры использования, возможные исключительные ситуации, особенности реализации.
Пример документирующего комментария к функции в программе на 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)
{
. . .
}
Популярные генераторы документации
Наиболее известные генераторы документации:
Wikimedia Foundation.
2010.
Полезное
Смотреть что такое "Документирующие комментарии" в других словарях:
Комментарии (программирование) — У этого термина существуют и другие значения, см. Комментарий. Комментарии пояснения к исходному тексту программы, находящиеся непосредственно внутри комментируемого кода. Синтаксис комментариев определяется языком программирования. С точки … Википедия
Комментарии в программировании — Комментарии пояснения к исходному тексту программы, находящиеся непосредственно внутри комментируемого кода. Синтаксис комментариев определяется языком программирования. С точки зрения компилятора или интерпретатора, комментарии часть текста… … Википедия
Генератор документации — Генератор документации программа или пакет программ, позволяющая получать документацию, предназначенную для программистов (документация на API) и/или для конечных пользователей системы, по особым образом комментированному исходному коду и,… … Википедия
Комментарий (программирование) — Комментарии пояснения к исходному тексту программы, находящиеся непосредственно внутри комментируемого кода. Синтаксис комментариев определяется языком программирования. С точки зрения компилятора или интерпретатора, комментарии часть текста… … Википедия
Документирующий комментарий — Генератор документации программа или пакет программ, позволяющая получать документацию, предназначенную для программистов (документация на API) и/или для конечных пользователей системы, по особым образом комментированному исходному коду и, в… … Википедия
Уотергейт — Отель Уотергейт Уотергейтский скандал (англ. Watergate scandal) политический скандал в США 1972 1974, закончившийся отставкой президента страны Ричарда Никсона. Единственный за всю историю США случай, когда президент прижизненно досрочно… … Википедия
Каноны «Звёздных войн» — впервые были упомянуты в первом выпуске журнала компании Lucasfilm «Star Wars Insider»: «Предание», или как мы его называем «канон», включает в себя сценарии, фильмы, радиопостановки и новеллизации. Одни работы появились благодаря… … Википедия
Уотергейтский скандал — Отель Уотергейт Уотергейтский скандал (англ. Watergate scandal) политический скандал в США 1972 … Википедия
Массовое убийство в школе «Колумбайн» — Эта статья или раздел нуждается в переработке. Пожалуйста, улучшите статью в соответствии с правилами написания статей … Википедия
Уотергейтское дело — Отель Уотергейт Уотергейтский скандал (англ. Watergate scandal) политический скандал в США 1972 1974, закончившийся отставкой президента страны Ричарда Никсона. Единственный за всю историю США случай, когда президент прижизненно досрочно… … Википедия