Doxygen против Javadoc [закрыто]
Я только что понял из статьи в CACM, что Doxygen работает с Java (и несколькими другими языками) тоже. Но Java уже имеет инструмент Javadoc. Может ли кто-нибудь объяснить, каковы плюсы и минусы любого подхода? Являются ли они взаимоисключающими? Есть ли плагин Maven для Doxygen?
4 ответа:
Doxygen имеет ряд функций, которые JavaDoc не предлагает, например, диаграммы классов для иерархий и контекста сотрудничества, дополнительные сводные страницы, дополнительный просмотр исходного кода (связанный с документацией), дополнительную поддержку тегов, таких как @todo на отдельной странице, и он может генерировать вывод в TeX и PDF format.It также позволяет много визуальной настройки.
поскольку Doxygen поддерживает стандартные теги JavaDoc, вы можете запускать Doxygen на любом исходном коде с помощью JavaDoc комментирует это. Часто даже имеет смысл работать с исходным кодом без JavaDoc, поскольку диаграммы и просмотр исходного кода могут помочь понять код даже без документации. И поскольку инструмент JavaDoc игнорирует неизвестные теги, вы можете даже использовать дополнительные теги Doxygen, не нарушая генерацию JavaDoc.
сказав все это, я должен признать, что я не использовал Doxygen в течение длительного времени. В настоящее время я склонен сильно полагаться на свою IDE, чтобы обеспечить ту же визуализацию, и я обычно не читают JavaDoc как HTML-страницы, но импортируют исходные файлы в мою IDE, чтобы он мог генерировать всплывающие окна JavaDoc, и я могу перейти к определениям. Это даже более мощно, чем то, что может предложить Доксиген. Если вы хотите иметь документацию за пределами IDE и рады запускать инструменты, отличные от Java, то Doxygen стоит попробовать, так как он не требует никаких изменений в вашем коде Java.
Я бы использовал Doxygen только с Java, если вы новичок в Java, и вы использовали Doxygen раньше, уменьшая кривую обучения, которую вы испытали бы с javadoc. Если вы раньше не использовали Doxygen, я бы придерживался javadoc, так как он был специально разработан с учетом Java. Если вы не знаете ни одного из них, и вы работаете на C++ (или других поддерживаемых языках) так же, как и на Java, Doxygen-хороший выбор, поскольку вы сможете использовать его для обоих языков.
оба инструмента просты в использовании, с аналогичный набор функций. Оба имеют плагины (или предварительно встроенные) для NetBeans и Eclipse, что делает его еще быстрее для создания doc. Существует много перекрытий в стиле комментариев, используемых каждым, но они не ровно то же самое, так что было бы трудно смешать их вместе (вы должны были бы знать детали и, оставляя без внимания любые функции, которые являются специфичными для одного или другого). Я никогда не использовал его, но кажется плагин Maven для Помощи Doxygen.
Мне нравится тот факт, что с Doxygen вы можете получить диаграммы классов, отображаемые на той же странице, что и документация. Кроме того, мне нравится тот факт, что он связывает вас непосредственно с исходным кодом, если это необходимо. Я не знаю, если javadoc имеет эти функции, хотя.
одним из больших преимуществ JavaDocs является то, что они просто работают. Все необходимое для их сборки и просмотра включено в JDK, который вам уже нужно установить для компиляции ваших программ.
Doxygen, с другой стороны, может быть боль, чтобы настроить и получить работу правильно. но если он настроен правильно, он должен иметь возможность создавать PDF-файлы, RTFs и DocBooks, а также HTML. HTML-код не организован также по умолчанию в качестве документации с индексом.HTML-код выводит пустую страницу по умолчанию. Кроме того, встроенные классы и статические члены могут нуждаться в специальных флагах для включения в документацию, и если вы хотите создать PDF, вам, возможно, придется иметь дело с неприятностями вашего дистрибутива Linux, не имеющего необходимой команды pdflatex (например, Ubuntu/Mint недавно имели проблемы), поэтому, если вы просто apt-get установите его и запустите, вы можете получить экран, полный ошибок, даже с простой программой. По сравнению с легкостью получения javadoc автоматически при установке API, Doxygen setup может быть несчастный опыт. Как только вы преодолеете препятствия, он должен быть более гибким в работе с проектами, включающими больше, чем просто java.