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

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

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

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

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

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

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

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

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

Список дескрипторов phpDocumentor
Дескриптор	Описание	Пример
`@author`	Автор	/** * Sample File 2, phpDocumentor Quickstart * * Файл из документации к phpDocumentor * демонстрирующий способы комментирования. * @author Greg Beaver <[email protected]> * @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)
  {
      . . .
  }