Генератор документации

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

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

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

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

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

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

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

/**  * Sample File 2, phpDocumentor Quickstart  *   * Файл из документации к phpDocumentor  * демонстрирующий способы комментирования.  * @author Greg Beaver <cellog@php.net>  * @version 1.0  * @package sample  * @subpackage classes  */ 

/**  * DocBlock для глобальной переменной  * @global integer $GLOBALS['myvar'] далее идет функция с с глобальной переменной  * или глобальная переменная, в этом случае необходимо указать ее имя  * @name $myvar  */  $GLOBALS['myvar'] = 6; 

/** * @staticvar integer $staticvar * @return возвращает целое значение */ 

/**  * 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 http://www.example.com встроенной гиперссылки} */ 

/**  * @deprecated   описание  * @deprec       синоним для deprecated  */ 

/**  * @abstract  * @access       public или private  * @copyright    Имя дата  * @example      /path/to/example  * @ignore  * @internal     закрытая информация для специалистов  * @param        тип [$varname] описание входного параметра  * @return       тип описание возвращаемого значения  * @see          имя другого элемента (ссылка)  * @since        версия или дата  * @static  */ 

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

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

• 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.