Муравей - Сборка документации

Документация необходима в любом проекте. Документация играет большую роль в поддержке проекта. Java упрощает документацию за счет использования встроенныхjavadocинструмент. Ant делает это еще проще, создавая документацию по запросу.

Как вы знаете, инструмент javadoc очень гибкий и позволяет использовать ряд параметров конфигурации. Ant предоставляет эти параметры конфигурации через задачу javadoc. Если вы не знакомы с javadocs, мы предлагаем вам начать с этого Руководства по документации Java .

В следующем разделе перечислены наиболее часто используемые параметры javadoc, которые используются в Ant.

Атрибуты

Источник можно указать с помощью sourcepath, sourcepathref или sourcefiles.

sourcepath используется для указания папки исходных файлов (например, папки src).
sourcepathref используется для ссылки на путь, на который ссылается атрибут пути (например, delegates.src.dir).
sourcefiles используется, когда вы хотите указать отдельные файлы в виде списка, разделенного запятыми.

Путь назначения указывается с помощью destdir папка (например, build.dir).

Вы можете отфильтровать javadocзадача, указав имена пакетов, которые нужно включить. Это достигается за счет использованияpackagenames атрибут, список файлов пакетов, разделенных запятыми.

Вы можете отфильтровать процесс javadoc, чтобы отображать только общедоступные, частные, пакетные или защищенные классы и члены. Это достигается за счет использованияprivate, public, package а также protected атрибуты.

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

Вы также можете сгруппировать пакеты, используя group атрибут, чтобы стало легче ориентироваться.

Собираем все вместе

Продолжим нашу тему Hello worldПриложение для факса. Давайте добавим цель документации в наш проект приложения «Факс».

Ниже приведен пример задачи javadoc, используемой в нашем проекте. В этом примере мы указали javadoc для использованияsrc.dir в качестве исходного каталога и doc как цель.

Мы также настроили заголовок окна, заголовок и информацию о нижнем колонтитуле, которая отображается на страницах документации java.

Также мы создали три группы -

один для служебных классов в нашей исходной папке,
один для классов пользовательских интерфейсов и
один для классов, связанных с базой данных.

Вы можете заметить, что в группе пакетов данных есть два пакета - faxapp.entity и faxapp.dao.

<target name = "generate-javadoc">
   <javadoc packagenames = "faxapp.*" sourcepath = "${src.dir}" 
      destdir = "doc" version = "true" windowtitle = "Fax Application">
      
      <doctitle><![CDATA[= Fax Application =]]></doctitle>
      
      <bottom>
         <![CDATA[Copyright © 2011. All Rights Reserved.]]>
      </bottom>
      
      <group title = "util packages" packages = "faxapp.util.*"/>
      <group title = "web packages" packages = "faxapp.web.*"/>
      <group title = "data packages" packages = "faxapp.entity.*:faxapp.dao.*"/>
   </javadoc>

   <echo message = "java doc has been generated!" />
</target>

Давайте выполним задачу javadoc Ant. Он генерирует и помещает файлы документации Java в папку doc.

Когда javadoc target выполняется, он дает следующий результат -

C:\>ant generate-javadoc
Buildfile: C:\build.xml

java doc has been generated!

BUILD SUCCESSFUL
Total time: 10.63 second

Файлы документации java теперь присутствуют в doc папка.

Обычно файлы javadoc создаются как часть целевого выпуска или пакета.