Учебники

Ant — Сборка документации

Май 16, 2019

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

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

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

Атрибуты

Источник может быть указан с использованием sourcepath , sourcepathref или sourcefiles .

  • sourcepath используется для указания на папку с исходными файлами (например, папка src).

  • sourcepathref используется для ссылки на путь, на который ссылается атрибут пути (например, Delegates.src.dir).

  • Исходные файлы используются, когда вы хотите указать отдельные файлы в виде списка через запятую.

sourcepath используется для указания на папку с исходными файлами (например, папка src).

sourcepathref используется для ссылки на путь, на который ссылается атрибут пути (например, Delegates.src.dir).

Исходные файлы используются, когда вы хотите указать отдельные файлы в виде списка через запятую.

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

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

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

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

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

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

Давайте продолжим нашу тему приложения Hello world Fax. Давайте добавим цель документации в наш проект приложения Fax.

Ниже приведен пример задачи 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>

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

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

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

java doc has been generated!

BUILD SUCCESSFUL
Total time: 10.63 second

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

Как правило, файлы javadoc создаются как часть целей выпуска или пакета.

55
Share: