?

Log in

No account? Create an account

Ср, 20 дек, 2006, 19:15
Doxygen vs phpDocumentor

Последнее время меня терзают смутные сомнения, правильно ли я сделал, что выбрал доксиген...
Сегодня часа три убил на более детальное ковыряние в doxygen'е и в phpDocumentor'e...
И попробовал всё разложить по полочкам, какие плюсы есть у того и другого (возможно что-то где-то упустил/не понял, но это те данные, которыми я обладаю на данный момент).


Специфика PHP


Doxygen - 2


При использовании доксигена нельзя указать тип св-ва/параметра. Отсюда получаем в документации просто имя с описанием, без типа.
Причём если мы используем Zend Studio нужно этот тип эммулировать у параметра метода/функции, чтоб Zend верное его отображал в инспекторе.
Т.е. формат команды @param у доксигена такой: @param <parameter-name> { parameter description }
А у Zend'а (он заточен на phpDocumentor), такой: @param <parameter-name> <parameter-type> { parameter description }
либо @param <parameter-type> <parameter-name> { parameter description }


Поэтому для того чтобы и зенд и доксиген понимали что где, приходиться описывать так:
@param $var1 string Параметр ла-ла-ла.
Соответственно "string" в документации отображается как часть описания. Хотя это и более-менее читабельно там выглядит, но совсем не то что нужно.

Аналогично с возвращаемым значением. Формат доксигена: @return <description>. Формат зенда: @return <type> <description>.
Так-же приходиться химичить и писать: @return string Возвращаем ла-ла-ла..

phpDocumentor - 4


Т.к. phpDocumentor заточен именно на PHP с этим у него всё окей. При чём если не описать тип, то он поставит mixed. Если не описать возвращаемого значение, то void.
Единственное что я не нашел как задать тип для константы класса.

Ссылки


Doxygen - 4


Что у доксигена мне нравиться, так это "Automatic link generation". Т.е. вы где-то в комментах пишите например DocExample::example(), и он автоматом преобразует это в ссылку на метод example() класса DocExample.
Единственный косяк - это то, что он не понимает ссылку на св-во класса (похоже опять из-за специфичного для PHP знака $ (бакса) перед именем переменной). На DocExample::$example нифига не сгенерит.

phpDocumentor - 3


Автоматической генерации линков нет, приходиться всё оборочивать в inline {@link} и/или юзать @see.
Например:
<?
/**
 * Описание.
 * Ссылка: {@link DocExample}. Сcылка на метод: {@link DocExample::example()}.
 * Ссылка на переменную: {@link DocExample::$example2}.
 * Ещё ссылка: {@link DocExample::example() метод example2()}
 * @see DocExample
 * @see DocExample::example(),DocExample::$example2
 */
?>

Юзабильность @see мне вообще кажется сомнительной.

Авто-вырезание короткого описания


Doxygen - 5


Есть такой, как мне кажется, замечательный параметр у доксигена: JAVADOC_AUTOBRIEF. При его включении за короткое описание будет браться первое предложение.
Пример:
<?
/**
 * Короткий коммент. Большой-большой.
 * Ну прям очень большой,
 * в несколько строк расширенный коммент.
 */
protected $example3;
?>

Плюс есть параметр REPEAT_BRIEF. Если он включен то короткое описание будет повторенно при выводе расшериенного.


phpDocumentor - 3


У phpDocumentor'а тоже есть вроде подобное: javadocdesc. Но толи это не то же самое, толи руки у меня кривые, но заставить его работать я не смог.
Поэтому приходиться писать так:
<?
/**
 * Короткий комент.
 *
 * Большой-большой. Ну прям очень большой,
 * в несколько строк расширенный коммент.
 */
protected $example3;
?>


Короткий формат docblock'а


Doxygen - 5


Куча всяких возможностей:
<?
//! Короткий коммент к константе/свойству.
const EXAMPLE1 = 1;

//! Короткий коммент к константе/свойству.
/*! Расширенное описание. Без короткого комента работать не будет! */
public $example2;

/**
 * Короткий комент. Большой-большой.
 * Ну прям очень большой,
 * в несколько строк расширеннт коммент.
 */
protected $example3;
?>


phpDocumentor - 2


Только один стиль:
<?
/**
 * Короткий коммент к константе/свойству.
 */
const EXAMPLE1 = 1;

/**
 * Короткий коммент к константе/свойству.
 *
 * Расширенное описание. Без короткого комента работать не будет!
 * @var int
 */
public $example2;

/**
 * Короткий комент.
 *
 * Большой-большой. Ну прям очень большой,
 * в несколько строк расширеннт коммент.
 * @var string
 */
protected $example3;
?>

Что очень громоздко. И если к классе много свойств выглядит это всё ужасно растянуто... Имхо читабельность кода сильно падает.

Одну строчку по идее можно сократить таким образом:
<?
/** Короткий коммент к константе/свойству.
 */
const EXAMPLE1 = 1;
?>

Но это как-то кривовато смотрится.

Хотя... Если учесть что нам все равно нада описывать типы (для phpDocumentor'а)... То возможно от таких больших комментов и не уйти.

Пакеты/группы


Doxygen - 5


Всё очень гибко. Сначало делается объявление группы: @defgroup <name> (group title).
Потом в коде указываем принадлежность чего-либо к этой группе. Причём можно указывать сразу несколько групп.
Есть возможность определять подгруппы, причём не ограниченной вложенности. В общем, красота!

phpDocumentor - 1


Есть категории, пакеты и подпакеты. Как к чего привязывать я до конца не понял. Т.к. нет явного описания (define).
Соответственно построить классификацию классов/модулей как-то становиться сложновато. Учитывая, что хотелось бы, чтоб один класс/модуль мог входить в неограниченное кол-во пакетов, и они могли бы иметь некую древовидную структуру.

Todo


Doxygen - 5


Их можно увидеть, как и в описании метода. Так и на спец. странице, где собранны все todo по проекту.

phpDocumentor - 1


Команда такая как бы есть, но вот в сгенерированной документации я так их и не увидел.
Похоже надо ещё какие-то телодвижения делать чтоб появилась страница с todo.

Диаграмма классов


Doxygen - 5


Для каждого класса генерируется диаграмма (рисунок), на которой видно от кого порождён класс и всех его потомков (максимальный уровень настраивается в конфиге). Причём рисунок кликабелен, если кликнуть на родителя, то отправишься на страницу родителя. Если кликнуть на потомка, то попадешь на страницу потомка.
Иногда бывает очень полезно. А главное это наглядно.

phpDocumentor - 1


Ничего такого нет.

Ещё 5 копеек


У доксигена намного больше настроек (даже если вычеркнуть всякие спец. настройки для конкретного языка или типа документации (html, chm, и т.д.)).
Мне кажется это ещё один плюс доксигену.




В общем хз. Охота и того, и другого, и лучше без хлеба:)
Так пока и не могу никак решить, что буду использовать:(

UPD: Doxygen vs phpDocumentor, часть 2. INPUT_FILTER

Ср, 20 дек, 2006 17:14 (UTC)
murrid

как решишь - отзвонись!

Пн, 8 фев, 2010 12:49 (UTC)
(Anonymous): Это сравнение значительно устарело...

Это сравнение значительно устарело... (да и полным его не назовешь...) =\
Какие версии Doxygen'а и phpDocumentor'а использовались?

По поводу phpDocumentor'а (с предыдущими версиями сразу скажу я не работал) хочется особенно отметить:
а) Страница todo есть (также инфа выводится и в описании элемента).
б) Ставить пустую строку между коротким и длинным комментарием не обязательно.
в) С "пакеты/группы" ставить phpDocumentor'у "1 балл" это явно перебор, ибо разделение всеже есть, пусть и слабенькое, но лично я считаю, что раскидать файлы и классы по категориям/подкатегорям - этого вполне достаточно (а если этого не достаточно, значит стоит задуматься).
г) "Авто-вырезание короткого описания" работает.

И вообще мне кажется что главное сравнивать не столько синтаксис, сколько то, что можно будет в конце получить - т.е. оценивать надо удобность сгенерированной документации, причем для разных проектов - очень больших, средних и маленьких, причем разделять их по количеству функций/констант/файлов/классов/наследований и пр.
Ибо к примеру если классы не используются в проекте то "Диаграмма классов" нафиг не нужна, а если проект маленький, то "Пакеты/группы" не нужны.

Вс, 9 янв, 2011 09:51 (UTC)
(Anonymous): беслатные секс знакомства

http://vkontakte.ru/id118356774
гей знакомства блу систем
интим знакомства сергиев посад
секс знакомства в ишимбае (http://vkontakte.ru/id118346125)
[url=http://vkontakte.ru/id118364192]знакомства с англичанами иностранцами сайты[/url]