Ant - buduj dokumentację

Dokumentacja jest niezbędna w każdym projekcie. Dokumentacja odgrywa wielką rolę w utrzymaniu projektu. Java ułatwia dokumentację dzięki wykorzystaniu wbudowanegojavadocnarzędzie. Ant czyni to jeszcze prostszym, generując dokumentację na żądanie.

Jak wiesz, narzędzie javadoc jest bardzo elastyczne i udostępnia wiele opcji konfiguracyjnych. Ant ujawnia te opcje konfiguracyjne za pomocą zadania javadoc. Jeśli nie znasz języka javadocs, zalecamy rozpoczęcie od tego samouczka dokumentacji Java .

W poniższej sekcji wymieniono najczęściej używane opcje javadoc używane w programie Ant.

Atrybuty

Źródło można określić za pomocą sourcepath, sourcepathref lub sourcefiles.

sourcepath służy do wskazywania folderu plików źródłowych (np. folder src).
sourcepathref służy do wskazywania ścieżki, do której odwołuje się atrybut ścieżki (np. delegates.src.dir).
sourcefiles jest używany, gdy chcesz określić poszczególne pliki jako listę oddzieloną przecinkami.

Ścieżka docelowa jest określana przy użyciu destdir folder (np. build.dir).

Możesz filtrować javadoczadanie, określając nazwy pakietów, które mają zostać uwzględnione. Osiąga się to za pomocąpackagenames atrybut, lista plików pakietu oddzielona przecinkami.

Można przefiltrować proces javadoc, aby wyświetlić tylko klasy i elementy publiczne, prywatne, pakietowe lub chronione. Osiąga się to za pomocąprivate, public, package i protected atrybuty.

Możesz również powiedzieć zadaniu javadoc, aby zawierało informacje o autorze i wersji przy użyciu odpowiednich atrybutów.

Możesz również zgrupować pakiety razem przy użyciu rozszerzenia group atrybut, aby nawigacja stała się łatwa.

Kładąc wszystko razem

Kontynuujmy nasz temat Hello worldAplikacja faksowa. Dodajmy docelową dokumentację do naszego projektu aplikacji faksowej.

Poniżej podano przykładowe zadanie javadoc użyte w naszym projekcie. W tym przykładzie określiliśmy javadoc do używaniasrc.dir jako katalog źródłowy i doc jako cel.

Dostosowaliśmy również tytuł okna, nagłówek i stopkę, które pojawiają się na stronach dokumentacji Java.

Stworzyliśmy również trzy grupy -

jeden dla klas narzędzi w naszym folderze źródłowym,
jeden dla klas interfejsów użytkownika i
jeden dla klas związanych z bazą danych.

Możesz zauważyć, że grupa pakietów danych ma dwa pakiety -– faxapp.entity i 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>

Wykonajmy zadanie Ant javadoc. Generuje i umieszcza pliki dokumentacji Java w folderze doc.

Kiedy javadoc target jest wykonywany, daje następujący wynik -

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

java doc has been generated!

BUILD SUCCESSFUL
Total time: 10.63 second

Pliki dokumentacji Java są teraz obecne w doc teczka.

Zazwyczaj pliki javadoc są generowane jako część docelowych wersji lub pakietu.