Вышел Doxygen 1.3.3

Объясните по-простому - что в нем хорошего?

Chioya proga voobshe ?

Тула позволяющая заниматься одним делом неотвлекаясь (писАть код) а документация генериться автоматически (по тагам/комментариям/коду). Вообще, любой другой вид написания документации (я здесь не говорю про книги/туториалы) - просто трата времени так как тот документ может устареть уже со следующей строки кода. А так как документ и сам код - это два "view" на одну модель ;-) то поддержание/синхронизация двух версий одного и тоже - непростительная роскошь.
java программисты хотя подобную тулу имеют - javadoc называется. Хотя опять-же - для консистенси в больших проектах и для жавы делают doxygen доки.

Он не доделан для php. Получается не очень хорошо, особенно для
процедурного стиля. Классы он неплохо раскладывает по полочкам.

Добрый день

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

С уважением Евгений

P.S. Комментарии конечно дело хорошее, но нормального описания они не заменят. P.P.S. Единственным исключением являются произведения от Кнута.

Тула просто супер!

Я ей пользовался - разгребает огромного размера проекты, и, если в них предстоит ещё и разбираться, штука просто незаменимая.

Она умеет перелопачивать код, находить там разнообразные функции, и в выходном HTML расставлять ссылки (не только это, конечно, но когда хочется посмотреть, что делает данная функция, просто шлёпаешь по ссылке и всё). Но для хорошей доки, надо, конечно, не лениться и писать комментарии...

Про плохую документацию: Ну уж нечего на зеркало пенять... как напишете, голубчик, так и получите. Про твёрдую копию: Дык она же, батенька, умеет и в *.rtf и в *.html загнать. А то и в LaTeX какой... Бери да распечатывай на бумаге любой твёрдости!

Про P.S.: так милай, это ж получается документация по API а на юзер гайд!

Простите вырвалось.... gordon

А я уже сказал что не говорю про твёрдую копию (документации слишком много - редкий случай). Просто когда много народу должны разбирать один код а дизайн ещё не устоялся (и посему не стоит тратить время на отдельную документацию которую надо будет от начала до конца просматривать снова и снова. И всё равно она будет всегда устаревшая из-за того что мы к сожалению однотредовые: если пишешь одно - то в этот момент уже не пишешь другое ;-) - то единственное решение иметь хоть какую-то доку (в противном случае - не будет никакой ;-) - это Doxygen либо javadoc). Только комментарии рядом с кодом так эффективны. Иначе я должен прыгать взад-вперёд между кодом и ещё чем-то и делать дополнительную синхронизационную работу которую за меня могет сделать компутер. Ну облом мне делать то что может за меня сделать комп. Иначе вообще никакой доки (кроме сырца) не будет Ж-)

doxygen генерирует .html, .rtf, .latex из последнего получатся шикарная твердая копия.
Вопрос не в переключении между текствым фалом документации и кодом а в поддержании консистентного состояния между кодом и документации.
Если результирующиие бинарные модули, примеры и документация генерятся из одного источника то эти затараты малы а расхождения находятся легче, в полуавтоматическом режиме (особенно если добавить еще пару tools-ов).
Никто опять же не мешает написать функциональную спецификацию в понятном doxygen формате, потом добавить техническую и уже потом к ней писать прототипы и классы а потом код.

>Я ей пользовался - разгребает огромного размера проекты, и, если в них предстоит ещё и разбираться, штука просто незаменимая.

Doxygen, конечно, и для этого очень хорош, но для, так скажем, "горячего" анализа кода лучшая тулза - Source Navigator от RedHat. "Попробовав раз - ем и сейчас". Крайне рекомендую!

Вопрос умным. Как в configure.in запихать автообнаружение doxygen в системе? Конкурс на самый красивый способ.

На всякий случай - это я не подначиваю, мне действительно интересно.

> Вопрос умным. Как в configure.in запихать автообнаружение doxygen в системе? Конкурс на самый красивый способ.

AC_PATH_PROG(HAVE_DOXYGEN, doxygen)

:))

Самый лучший способ - избавиться раз и навсегда от configure.in.

Stop the autoconf insanity!
http://freshmeat.net/articles/view/889/

Добрый день

Очень яркая иллюстрация к моим словам:

Документация к root пакету: http://root.cern.ch/root/Categories.html

Документация к paw: http://wwwasd.web.cern.ch/wwwasd/paw/

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

Я не против автодокументации, но _нормальной_ документации она не заменит, то есть не надо обольщаться тем, что doxygen избавит вас от необходимости писать документацию, на которую придётся потратить половину времени (в прямом смысле этого слова).

С уважением Евгений

P.S. Оба упомятых мной проекта делают примерно одно и то же, только разница между ними примерно в двадцать лет. Ключевой фигурой и там и там был и есть Брун.

P.P.S. В rootе есть и User Guide - не фонтан, но лучше чем автодокументация.

P.P.P.S. Естественно всё сказанное есть моё IMHO.

Противоположенный пример :)

Документация к QT -- одна из лучших, понятная и логичная (это, кстати, не только мое мнение). Генериться доксигеном.

Спасибо. Я думал что-то подобное. А он не детектируется через pkgconfig?

afaik нет.

но написать свой doxygen.pc. imho - пара пустяков :))

хотя не буду врать, doxygen-ом не пользуюсь. к сожалению, от нас требуют доки согласно 19 ГОСТ-у. и любые доксигены тут безсильны :(