Единая система программной документации
- 1 year ago
- 0
- 0
Генератор документации — программа или пакет программ , позволяющая получать документацию , предназначенную для программистов (документация на 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)
{
. . .
}
Примеры для разных языков и сред программирования: