Генератор документации - NiNa.Az

Генератор документации — программа или пакет программ, позволяющая получать документацию, предназначенную для программистов (документация на API) и/или для конечных пользователей системы, по особым образом комментированному исходному коду и, в некоторых случаях, по исполняемым модулям (полученным на выходе компилятора).

Обычно генератор анализирует исходный код программы, выделяя синтаксические конструкции, соответствующие значимым объектам программы (типам, классам и их членам/свойствам/методам, процедурам/функциям и т. п.). В ходе анализа также используется мета-информация об объектах программы, представленная в виде документирующих комментариев. На основе всей собранной информации формируется готовая документация, как правило, в одном из общепринятых форматов — HTML, HTMLHelp, PDF, RTF и других.

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

Документирующий комментарий — это особым образом оформленный комментарий к объекту программы, предназначенный для использования каким-либо конкретным генератором документации. От того, какой генератор документации применяется, зависит синтаксис конструкций, используемых в документирующих комментариях.

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

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

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

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

Список дескрипторов phpDocumentor
Дескриптор	Описание	Пример
@author	Автор	/** * Sample File 2, phpDocumentor Quickstart * * Файл из документации к phpDocumentor * демонстрирующий способы комментирования. * @author Greg Beaver <[e-mail]> * @version 1.0 * @package sample * @subpackage classes */
@version	Версия кода
@package	Указывает пакет к которому относится код
@subpackage	Указывает подпакет
@global	Описание глобальных переменных	/** * DocBlock для глобальной переменной * @global integer $GLOBALS['myvar'] далее идет функция с с глобальной переменной * или глобальная переменная, в этом случае необходимо указать ее имя * @name $myvar */ $GLOBALS['myvar'] = 6;
@name	Имя, метка
@staticvar	Описание статических переменных	/** * @staticvar integer $staticvar * @return возвращает целое значение */
@return	Описание возвращаемого значения
@todo	Заметки для последующей реализации.	/** * DocBlock с вложенными списками * @todo Простой TODO список * - item 1 * - item 2 * - item 3 * @todo Вложенный TODO список * <ol> * <li>item 1.0</li> * <li>item 2.0</li> * <ol> * <li>item 2.1</li> * <li>item 2.2</li> * </ol> * <li>item 3.0</li> * </ol> */
@link	Ссылка	/** * Это пример {@link http://www.example.com встроенной гиперссылки} */
@deprecated (@deprec)	Описание устаревшего блока	/** * @deprecated описание * @deprec синоним для deprecated */
@example	Пример	/** * @abstract * @access public или private * @copyright Имя дата * @example /path/to/example * @ignore * @internal закрытая информация для специалистов * @param тип [$varname] описание входного параметра * @return тип описание возвращаемого значения * @see имя другого элемента (ссылка) * @since версия или дата * @static */
@see	Ссылка на другое место в документации
Другие дескрипторы
@copyright  · @license  · @filesource  · @category  · @since  · @abstract  · @access  · @example  · @ignore  · @internal  · @static  · @throws  · @uses  · @tutorial

Пример документирующего комментария к функции в программе на 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)  {  . . .  } 

Популярные генераторы документации

Примеры для разных языков и сред программирования:

• ^[англ.];
• предназначен для программ на языке 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;
•  — языке Python;
•  — языке Delphi/Pascal;
•  — языке Perl (включен в стандартный дистрибутив);
• PhpDocumentor и PHPDoc (адаптация Javadoc для использования с PHP) — языке PHP;
• POD (англ.);
•  — языке Ruby;
• ;
• TwinText (англ.);
•  — языках C#, VB.NET и других языках платформы .NET;
• Sandcastle — для C#, VB.NET и других языков платформы .NET;
• Sphinx — языке Python;
•  — языке VB6;
• VSdocman (ранее VBdocman .NET) — языков VB.NET и C#;
• WEB / ;
• XHelpGen — языке Delphi (входит в состав библиотеки KOL/MCK).
• PHPDox — проекты PHP.

Примечания

1. HappyDoc Source Documentation  (неопр.). Дата обращения: 27 января 2006. Архивировано 27 ноября 2020 года.
2. PasDoc — pasdoc  (неопр.). Дата обращения: 7 сентября 2009. Архивировано 20 декабря 2016 года.
3. Perl programming documentation — perldoc.perl.org  (неопр.). Дата обращения: 17 июня 2009. Архивировано 30 января 2009 года.
4. RDoc — Document Generator for Ruby Source  (неопр.). Дата обращения: 19 июня 2022. Архивировано 6 июня 2022 года.
5. ROBODoc — automating the software documentation process  (неопр.). Дата обращения: 27 января 2006. Архивировано 13 мая 2011 года.
6. NDoc Online  (неопр.). Дата обращения: 27 января 2006. Архивировано 3 июля 2006 года.
7. Doug Hellmann, Writing Technical Documentation with Sphinx, Paver, and Cog Архивная копия от 16 января 2013 на Wayback Machine
8. http://www.helixoft.com/vbdocman/ (недоступная ссылка)
9. Knuth and Levy:CWEB Архивировано 20 ноября 2012 года.