Лучшие вопросы
Таймлайн
Чат
Перспективы
Генератор документации
Из Википедии, свободной энциклопедии
Remove ads
Генератор документации — программа или пакет программ, позволяющая получать документацию, предназначенную для программистов (документация на API) и/или для конечных пользователей системы, по особым образом комментированному исходному коду и, в некоторых случаях, по исполняемым модулям (полученным на выходе компилятора).
Обычно генератор анализирует исходный код программы, выделяя синтаксические конструкции, соответствующие значимым объектам программы (типам, классам и их членам/свойствам/методам, процедурам/функциям и т. п.). В ходе анализа также используется мета-информация об объектах программы, представленная в виде документирующих комментариев. На основе всей собранной информации формируется готовая документация, как правило, в одном из общепринятых форматов — HTML, HTMLHelp, PDF, RTF и других.
Remove ads
Документирующие комментарии
Суммиров вкратце
Перспектива
Документирующий комментарий — это особым образом оформленный комментарий к объекту программы, предназначенный для использования каким-либо конкретным генератором документации. От того, какой генератор документации применяется, зависит синтаксис конструкций, используемых в документирующих комментариях.
В документирующих комментариях может содержаться информация об авторе кода, описываться назначение объекта программы, смысл входных и выходных параметров — для функции/процедуры, примеры использования, возможные исключительные ситуации, особенности реализации.
Документирующие комментарии, как правило, оформляются как многострочные комментарии в стиле языка Си. В каждом случае комментарий должен находиться перед документируемым элементом. Первым символом в комментарии (и в начале строк комментария) должен быть *
. Блоки разделяются пустыми строками.
Пример документирующего комментария на языке PHP:
/**
* Имя или краткое описание объекта
*
* Развернутое описание
*
* @имя_дескриптора значение
* @return тип_данных
*/
Пример документирующего комментария к функции в программе на 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)
{
. . .
}
Remove ads
Популярные генераторы документации
Примеры для разных языков и сред программирования:
- Doc-O-Matic[англ.];
- Document! X предназначен для программ на языке VB6, языках: VB.NET/C#/Visual C++ .NET (.NET Framework 1.0, 1.1 и 2.0), COM-компонентов, баз данных Access, Microsoft SQL Server и Oracle, XML Schema и других языках описания XML;
- Doxygen — языках: C++, Си, Objective-C, Java, IDL, PHP, C#, Фортран, VHDL, Python и, частично, D;
- Epydoc — языке Python;
- Javadoc — языке Java;
- JSDoc — языке JavaScript;
- HappyDoc[1] — языке Python;
- PasDoc[2] — языке Delphi/Pascal;
- perldoc[3] — языке Perl (включен в стандартный дистрибутив);
- PhpDocumentor и PHPDoc (адаптация Javadoc для использования с PHP) — языке PHP;
- POD (англ.);
- RDoc[4] — языке Ruby;
- ROBODoc[5];
- TwinText (англ.);
- NDoc[6] — языках C#, VB.NET и других языках платформы .NET;
- Sandcastle — для C#, VB.NET и других языков платформы .NET;
- Sphinx — языке Python[7];
- VBdocman[8] — языке VB6;
- VSdocman (ранее VBdocman .NET) — языков VB.NET и C#;
- WEB / CWEB[9];
- XHelpGen — языке Delphi (входит в состав библиотеки KOL/MCK).
- PHPDox — проекты PHP.
Remove ads
Примечания
Wikiwand - on
Seamless Wikipedia browsing. On steroids.
Remove ads