Интернет магазин китайских планшетных компьютеров

Компьютеры - Генератор документации

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

Обычно генератор анализирует исходный код программы, выделяя синтаксические конструкции, соответствующие значимым объектам программы. В ходе анализа также используется мета-информация об объектах программы, представленная в виде документирующих комментариев. На основе всей собранной информации формируется готовая документация, как правило, в одном из общепринятых форматов — 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 далее идет функция с с глобальной переменной
 * или глобальная переменная, в этом случае необходимо указать ее имя
 * @name $myvar
 */ 
$GLOBALS = 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        тип описание входного параметра
 * @return       тип описание возвращаемого значения
 * @see          имя другого элемента
 * @since        версия или дата
 * @static
 */

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

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