Wprowadzenie do Javadoc

1. Przegląd

Dobra dokumentacja API jest jednym z wielu czynników przyczyniających się do ogólnego sukcesu projektu oprogramowania.

Na szczęście wszystkie współczesne wersje JDK udostępniają narzędzie Javadoc - do generowania dokumentacji API z komentarzy obecnych w kodzie źródłowym.

Wymagania wstępne:

  1. JDK 1.4 (JDK 7+ jest zalecany do najnowszej wersji wtyczki Maven Javadoc)
  2. Folder JDK / bin dodany do zmiennej środowiskowej PATH
  3. (Opcjonalnie) IDE z wbudowanymi narzędziami

2. Komentarze Javadoc

Zacznijmy od komentarzy.

Struktura komentarzy Javadoc wygląda bardzo podobnie do zwykłego komentarza wieloliniowego , ale kluczową różnicą jest dodatkowa gwiazdka na początku:

// This is a single line comment /* * This is a regular multi-line comment */ /** * This is a Javadoc */

Komentarze w stylu Javadoc mogą również zawierać znaczniki HTML.

2.1. Format Javadoc

Komentarze Javadoc mogą być umieszczane nad dowolną klasą, metodą lub polem, które chcemy udokumentować.

Komentarze te zwykle składają się z dwóch części:

  1. Opis tego, co komentujemy
  2. Samodzielne znaczniki blokowe (oznaczone symbolem „ @ ”), które opisują określone metadane

W naszym przykładzie będziemy używać bardziej popularnych tagów blokowych. Pełną listę tagów bloków można znaleźć w przewodniku informacyjnym.

2.2. Javadoc na poziomie klasy

Przyjrzyjmy się, jak wyglądałby komentarz Javadoc na poziomie klasy:

/** * Hero is the main entity we'll be using to . . . * * Please see the {@link com.baeldung.javadoc.Person} class for true identity * @author Captain America * */ public class SuperHero extends Person { // fields and methods }

Mamy krótki opis i dwa różne tagi blokowe - samodzielne i wbudowane:

  • Samodzielne tagi pojawiają się po opisie z tagiem jako pierwszym słowem w linii, np. Tag @author
  • Tagi wbudowane mogą pojawić się w dowolnym miejscu i są otoczone nawiasami klamrowymi , np. Znacznik @link w opisie

W naszym przykładzie możemy również zobaczyć dwa rodzaje używanych tagów blokowych:

  • {@link} zawiera wbudowany link do wskazanej części naszego kodu źródłowego
  • @author nazwa autora, który dodał komentowaną klasę, metodę lub pole

2.3. Javadoc na poziomie pola

Możemy również użyć opisu bez żadnych tagów blokowych, takich jak ten w naszej klasie SuperHero :

/** * The public name of a hero that is common knowledge */ private String heroName;

Pola prywatne nie będą miały Javadoc generowany dla nich, chyba że wyraźnie zdać -prywatny opcję do polecenia Javadoc.

2.4. Javadoc na poziomie metody

Metody mogą zawierać różne znaczniki bloków Javadoc.

Rzućmy okiem na metodę, której używamy:

/** * 

This is a simple description of the method. . . * Superman! *

* @param incomingDamage the amount of incoming damage * @return the amount of health hero has after attack * @see HERO-402 * @since 1.0 */ public int successfullyAttacked(int incomingDamage) { // do things return 0; }

SuccessfullyAttacked metoda zawiera zarówno opis i liczne znaczniki blokowe samodzielna.

Istnieje wiele tagów blokowych, które pomagają w generowaniu prawidłowej dokumentacji, i możemy zawierać różnego rodzaju informacje. W komentarzach możemy nawet wykorzystać podstawowe znaczniki HTML.

Przyjrzyjmy się tagom, które napotkamy w powyższym przykładzie:

  • @param zawiera wszelkie przydatne opisy parametrów metody lub danych wejściowych, których powinien się spodziewać
  • @return zawiera opis tego, co metoda zwróci lub może zwrócić
  • @see wygeneruje link podobny do tagu {@link} , ale bardziej w kontekście odniesienia, a nie w treści
  • @since określa, która wersja klasy, pola lub metody została dodana do projektu
  • @version określa wersję oprogramowania, powszechnie używaną z makrami% I% i% G%
  • @throws służy do dalszego wyjaśniania przypadków, w których oprogramowanie oczekiwałoby wyjątku
  • @deprecated zawiera wyjaśnienie, dlaczego kod został wycofany, kiedy mógł być przestarzały i jakie są alternatywy

Chociaż obie sekcje są technicznie opcjonalne, będziemy potrzebować co najmniej jednej, aby narzędzie Javadoc wygenerowało cokolwiek znaczącego.

3. Generowanie Javadoc

Aby wygenerować nasze strony Javadoc, będziemy chcieli przyjrzeć się narzędziu wiersza poleceń, które jest dostarczane z JDK i wtyczką Maven.

3.1. Narzędzie wiersza poleceń Javadoc

Narzędzie wiersza poleceń Javadoc jest bardzo potężne, ale wiąże się z nim pewna złożoność.

Uruchomienie polecenia javadoc bez żadnych opcji ani parametrów spowoduje błąd i oczekiwane parametry wyjściowe.

Będziemy musieli przynajmniej określić, dla jakiego pakietu lub klasy ma być generowana dokumentacja.

Otwórzmy wiersz poleceń i przejdźmy do katalogu projektu.

Zakładając, że wszystkie klasy znajdują się w folderze src w katalogu projektu:

[email protected]:~$ javadoc -d doc src\*

Spowoduje to wygenerowanie dokumentacji w katalogu o nazwie doc, zgodnie z flagą - d . Jeśli istnieje wiele pakietów lub plików, musielibyśmy dostarczyć je wszystkie.

Korzystanie ze środowiska IDE z wbudowaną funkcjonalnością jest oczywiście łatwiejsze i ogólnie zalecane.

3.2. Javadoc z wtyczką Maven

We can also make use of the Maven Javadoc plugin:

   org.apache.maven.plugins maven-javadoc-plugin 3.0.0  1.8 1.8   ...    

In the base directory of the project, we run the command to generate our Javadocs to a directory in target\site:

[email protected]:~$ mvn javadoc:javadoc

The Maven plugin is very powerful and facilitates complex document generation seamlessly.

Let's now see what a generated Javadoc page looks like:

We can see a tree view of the classes our SuperHero class extends. We can see our description, fields, and method, and we can click on links for more information.

A detailed view of our method looks like this:

3.3. Custom Javadoc Tags

In addition to using predefined block tags to format our documentation, we can also create custom block tags.

In order to do so, we just need to include a -tag option to our Javadoc command line in the format of ::.

In order to create a custom tag called @location allowed anywhere, which is displayed in the “Notable Locations” header in our generated document, we need to run:

[email protected]:~$ javadoc -tag location:a:"Notable Locations:" -d doc src\*

In order to use this tag, we can add it to the block section of a Javadoc comment:

/** * This is an example... * @location New York * @returns blah blah */

The Maven Javadoc plugin is flexible enough to also allow definitions of our custom tags in our pom.xml.

In order to set up the same tag above for our project, we can add the following to the section of our plugin:

...   location a Notable Places:   ...

This way allows us to specify the custom tag once, instead of specifying it every time.

4. Conclusion

Ten krótki samouczek wprowadzający dotyczył pisania podstawowych Javadoc i generowania ich za pomocą wiersza poleceń Javadoc.

Łatwiejszym sposobem generowania dokumentacji byłoby użycie jakichkolwiek wbudowanych opcji IDE lub włączenie wtyczki Maven do naszego pliku pom.xml i uruchomienie odpowiednich poleceń.

Przykłady kodu, jak zawsze, można znaleźć na GitHub.