Doxygen против Javadoc [закрыто]

Question

Я только что понял из статьи в CACM, что Doxygen также работает с Java (и несколькими другими языками). Но в Java уже есть инструмент Javadoc. Может кто-нибудь объяснить, в чем плюсы и минусы любого подхода? Они взаимоисключающие? Есть ли плагин Maven для Doxygen?

Answer 1

Doxygen имеет ряд функций, которые не предлагает JavaDoc, например, диаграммы классов для иерархий и контекста сотрудничества, дополнительные сводные страницы, дополнительный просмотр исходного кода (перекрестно связанный с документацией), дополнительная поддержка тегов, например @todo, на отдельной странице, и она может генерировать выходные данные в формате TeX и PDF .Это также позволяет много визуальной настройки.

Поскольку Doxygen поддерживает стандартные теги JavaDoc, вы можете запускать Doxygen для любого исходного кода с комментариями JavaDoc. Часто даже имеет смысл запускать исходный код без JavaDoc, поскольку диаграммы и просмотр исходного кода могут помочь понять код даже без документации. А поскольку инструмент JavaDoc игнорирует неизвестные теги, вы даже можете использовать дополнительные теги Doxygen, не прерывая генерацию JavaDoc.

Сказав все это, я должен признать, что давно не употреблял Doxygen. В настоящее время я в значительной степени полагаюсь на мою среду IDE для обеспечения той же визуализации, и обычно я не читаю JavaDoc как HTML-страницы, а импортирую исходные файлы в мою среду IDE, чтобы она могла генерировать всплывающие подсказки JavaDoc, и я могу переходить к определениям. Это даже сильнее, чем то, что может предложить Doxygen. Если вы хотите иметь документацию за пределами IDE и готовы запускать инструменты, отличные от Java, то стоит попробовать Doxygen, поскольку он не требует никаких изменений в вашем Java-коде.

Answer 2

Я бы использовал Doxygen с Java только в том случае, если вы новичок в Java и ранее уже использовали Doxygen, что сокращает время обучения, которое вы испытываете с javadoc. Если вы раньше не использовали Doxygen, я бы остановился на javadoc, так как он был специально разработан с учетом Java. Если вы не знаете ни одного, и работаете на C ++ (или других поддерживаемых языках) столько же, сколько и на Java, Doxygen - хороший выбор, поскольку вы сможете использовать его для обоих языков.

Оба инструмента просты в использовании, с похожим набором функций. Оба имеют плагины (или уже встроены) для NetBeans и Eclipse, что позволяет еще быстрее создавать документы. Существует много совпадений в стиле комментариев, используемых каждым, но они не являются точно одинаковыми, поэтому было бы сложно смешать их вместе (вам нужно знать детали < em> both , исключая любые функции, относящиеся к одному или другому). Я никогда не использовал его, но, похоже, есть плагин Maven для Doxygen .

Answer 3

Мне нравится тот факт, что с Doxygen вы можете отображать диаграммы классов на той же странице, что и документация. Кроме того, мне нравится тот факт, что он связывает вас напрямую с исходным кодом, если это необходимо. Я не знаю, есть ли у Javadoc такие возможности.

Answer 4

Одним из больших преимуществ JavaDocs является то, что они просто работают. Все необходимое для их сборки и просмотра включено в JDK, который вам уже нужно установить для компиляции ваших программ.

Doxygen, с другой стороны, может быть затруднительным для настройки и правильной работы. но если он настроен правильно, он должен иметь возможность генерировать PDF, RTF и DocBooks, а также HTML. HTML по умолчанию не организован так же, как JavaDocs, так как index.html по умолчанию вызывает пустую страницу. Кроме того, встроенные классы и статические члены могут нуждаться в специальных флагах для включения в документацию, и если вы хотите сгенерировать PDF, вам, возможно, придется столкнуться с трудностями вашего дистрибутива Linux, не имеющими нужной команды pdflatex (например, Ubuntu / Mint имел проблемы в последнее время), так что если вы просто установите и запустите apt-get, вы можете получить экран, полный ошибок, даже с простой программой. По сравнению с простотой автоматического получения javadoc при установке API, установка Doxygen может быть очень неприятной. Как только вы преодолеете препятствия, он должен быть более гибким в работе с проектами, включающими не только Java.