9 июня 2007 в 15:19
Doxygen это система генерирования документации для C++, C, Java, Python, IDL
(Corba и разновидности от Microsoft), а также в некоторой степени для PHP, C#, и D.
Документация извлекается непосредственно из исходников, это помогает хранить документацию
в соответствии с исходным кодом.
Doxygen
распространяется автором, Dimitri van Heesch,
по лицензии
GNU GPL. На сайте Doxygen есть прекрасное
руководство. А все нижеследующие примечания относятся к реализации разработки для
Drupal в Doxygen-совместимом формате.
Основной синтаксис документации
Для документирования блока кода, используется следующий синтаксис:
<br />
* Это документация.
<br />
*/
Doxygen будет анализировать все комментарии в подобном блоке. Это стиль позволит
использовать некоторые Doxygen-специфичные команды, настолько, насколько это
возможно, сохраняя исходник разборчивым. Любые упоминания функций или имён файлов
в документации автоматически ссылаются на связанный код, и как правило, нет
необходимости введения разметки созданных связей.
Документирование файлов
Хорошей практикой является добавление в начало фйала описания его назначения.
Например:
<br/>
// $Id: profile.inc,v 1.0 2007/05/30 04:21:21 SadhooKlay Exp $
<br/>
<br/>
/**
<br/>
* [user=file]file[/user]
<br/>
* Система для работы с полями пользовательского профиля.
<br/>
*
<br/>
* Данная система позволяет настроить отображение практически
<br/>
* в любом виде, любого поля пользовательского профиля в Drupal.
<br/>
*/
В строке, следующей непосредственно за директивой [user=file]file[/user], краткое описание файла,
которое будет показано при отображении списка всех файлов в созданной документации.
Если строка начинается с глагола, глагол следует писать в настоящем времени,
например, «Управляет полями пользовательского профиля».
Дальнейшее описание может следовать после пустой строки.
Для добавления CVS ID-тега в ваш файл, укажите в начале файла // $Id$.
CVS автоматически расширит информацию о файле. Включайте, в секцию
// $Id$ информацию об имени файла, версии, дате последних изменений и
авторе. В последствии CVS будет обновлять эту информацию автоматически.
Подробную документацию по CVS можно получить на
официальном
сайте, в
Википедии и в
руководстве на drupal.org.
Документирование функций
Все функции, которые могут быть вызваны другими файлами должны быть документированы;
также, опционально, могут быть документированы и приватные функции.
Блок документирования функции должен предшествовать непосредственно перед объявлением
самой функции, Например вот так :
<br />
* Проверяет синтаксис текущего адреса электронной почты.
<br />
*
<br />
* Пустые e-mail адреса разрешены.
<br />
* За подробной информацией обратитесь к RFC 2822.
<br />
*
<br />
* [user=param]param[/user] $mail
<br />
* Строка, содержащая адрес.
<br />
* [user=return]return[/user]
<br />
* TRUE, если адрес находится в правильном формате.
<br />
* /
<br />
function valid_email_address($mail) {
Первая строка блока должна содержать краткое описание того, что из себя
представляет функция и должна начинаться например с «Управляет и
управляемый» (вместо «Для управления и управляемый»).
Развёрнутое описание может идти после пустой строки. Каждый параметр должен быть
предварён директивой [user=param]param[/user] и описан со следующей строки. После того как
все параметры описаны, следует описать директиву [user=return]return[/user], если возвращаемое
значение присутствует. Между директивами [user=param]param[/user] и [user=return]return[/user] не должно быть
пустых строк. Для функций, описание которых можно уместить в одной строке, эти
директивы можно опустить. Например:
<br />
* Конвертирует ассоциативный массив в анонимный объект.
<br />
* /
<br />
function array2object($array) {
Параметры и возвращаемое значение в этом случае, должны быть описаны в одной строке.
Документирование реализованных ловушек (hooks)
Многие модули в значительной степени состоят из реализации ловушек. Если реализация
является довольно стандартной и не требует более детального разъяснения, чем
прототип ловушки, достаточно использовать документирование в сокращенном виде:
<br />
* Реализация hook_help().
<br />
*/
<br />
function blog_help($section) {
Это создаст справку, способную в будущем напомнить разработчику о реализации
ловушки. Данное документирование не имеет Doxygen-параметров и возвращаемых
значений, что в принципе одинаково для описания любых реализаций ловушек.
Документирование функций темизации
В целях обеспечения оперативного введения в разрабатываемую тему,
описание всех функции темизации может быть сгруппировано на одной странице
документации. Даже если сами функции описаны в разных файлах. Для обеспечения такой
возможности добавьте инструкцию группировки для любых возможных функций:
<br />
* Определение темизированной функции pager
<br />
*
<br />
* ...
<br />
* [user=ingroup]ingroup[/user] themeable
<br />
*/
<br />
function theme_pager($tags = array(), $limit = 10, $element = 0, $attributes = array()) {
<br />
...
<br />
}
Этот же шаблон документирования, в целях группирования единой справочной
документации, может быть использован для любых других функций темизации,
используемых в вашей разрабатываемой теме оформления.
