Java - komentarze do dokumentacji
Język Java obsługuje trzy typy komentarzy -
| Sr.No. | Komentarz i opis |
|---|---|
| 1 | /* text */ Kompilator ignoruje wszystko od / * do * /. |
| 2 | //text Kompilator ignoruje wszystko od // do końca wiersza. |
| 3 | /** documentation */ To jest komentarz do dokumentacji i ogólnie jego nazwa doc comment. PlikJDK javadocnarzędzie wykorzystuje komentarze do dokumentów podczas przygotowywania automatycznie generowanej dokumentacji. |
Ten rozdział dotyczy wyjaśnienia Javadoc. Zobaczymy, jak możemy wykorzystać Javadoc do wygenerowania użytecznej dokumentacji dla kodu Java.
Co to jest Javadoc?
Javadoc jest narzędziem dostarczanym z JDK i służy do generowania dokumentacji kodu Java w formacie HTML z kodu źródłowego Java, co wymaga dokumentacji w predefiniowanym formacie.
Poniżej znajduje się prosty przykład, w którym linie wewnątrz /* ....*/ to wieloliniowe komentarze Java. Podobnie wiersz poprzedzający znak // to jednowierszowy komentarz Java.
Przykład
/**
* The HelloWorld program implements an application that
* simply displays "Hello World!" to the standard output.
*
* @author Zara Ali
* @version 1.0
* @since 2014-03-31
*/
public class HelloWorld {
public static void main(String[] args) {
// Prints Hello, World! on standard output.
System.out.println("Hello World!");
}
}W części opisu można umieścić wymagane znaczniki HTML. Na przykład w poniższym przykładzie użyto <h1> .... </h1> dla nagłówka, a <p> został użyty do utworzenia podziału akapitu -
Przykład
/**
* <h1>Hello, World!</h1>
* The HelloWorld program implements an application that
* simply displays "Hello World!" to the standard output.
* <p>
* Giving proper comments in your program makes it more
* user friendly and it is assumed as a high quality code.
*
*
* @author Zara Ali
* @version 1.0
* @since 2014-03-31
*/
public class HelloWorld {
public static void main(String[] args) {
// Prints Hello, World! on standard output.
System.out.println("Hello World!");
}
}Tagi javadoc
Narzędzie javadoc rozpoznaje następujące tagi -
| Etykietka | Opis | Składnia |
|---|---|---|
| @autor | Dodaje autora zajęć. | @author name-text |
| {@kod} | Wyświetla tekst czcionką kodu bez interpretowania tekstu jako znacznika HTML lub zagnieżdżonych znaczników javadoc. | {@code text} |
| {@docRoot} | Reprezentuje względną ścieżkę do katalogu głównego wygenerowanego dokumentu z dowolnej wygenerowanej strony. | {@docRoot} |
| @deprecated | Dodaje komentarz wskazujący, że ten interfejs API nie powinien być już używany. | @deprecated deprecatedtext |
| @wyjątek | Dodaje Throws podtytuł do wygenerowanej dokumentacji, z nazwą klasy i tekstem opisu. | Opis nazwy klasy @ wyjątku |
| {@inheritDoc} | Dziedziczy komentarz z nearest dziedziczona klasa lub implementowalny interfejs. | Dziedziczy komentarz z bezpośredniej klasy nadrzędnej. |
| {@połączyć} | Wstawia łącze w wierszu z widoczną etykietą tekstową, która wskazuje dokumentację dla określonego pakietu, klasy lub nazwy elementu członkowskiego klasy, do której się odwołuje. | {@link package.class # member label} |
| {@linkplain} | To samo, co {@link}, z tą różnicą, że etykieta linku jest wyświetlana zwykłym tekstem niż czcionka kodu. | {@linkplain package.class # etykieta członka} |
| @param | Dodaje parametr z określoną nazwą parametru, po którym następuje określony opis do sekcji „Parametry”. | @param opis nazwy parametru |
| @powrót | Dodaje sekcję „Zwroty” z tekstem opisu. | @return opis |
| @widzieć | Dodaje nagłówek „Zobacz też” z łączem lub wpisem tekstowym wskazującym na odniesienie. | @ zobacz odniesienie |
| @seryjny | Używany w komentarzu do dokumentu dla domyślnego pola możliwego do serializacji. | @serial field-description | zawiera | wykluczać |
| @serialData | Dokumentuje dane zapisane przez metody writeObject () lub writeExternal (). | @serialData data-description |
| @serialField | Dokumentuje składnik ObjectStreamField. | @serialField nazwa-pola typ-pola opis-pola |
| @od | Dodaje nagłówek „Od” z określonym tekstem od początku do wygenerowanej dokumentacji. | @ od wydania |
| @throws | Tagi @throws i @exception są synonimami. | @throws opis nazwy klasy |
| {@wartość} | Gdy {@value} jest używany w komentarzu dokumentu do pola statycznego, wyświetla wartość tej stałej. | {@value package.class # field} |
| @wersja | Dodaje podtytuł „Wersja” z określonym tekstem wersji do wygenerowanych dokumentów, gdy używana jest opcja -version. | @version version-text |
Przykład
Poniższy program używa kilku ważnych tagów dostępnych w komentarzach do dokumentacji. Możesz użyć innych tagów w zależności od swoich wymagań.
Dokumentacja dotycząca klasy AddNum zostanie utworzona w pliku HTML AddNum.html, ale jednocześnie zostanie również utworzony plik główny o nazwie index.html.
import java.io.*;
/**
* <h1>Add Two Numbers!</h1>
* The AddNum program implements an application that
* simply adds two given integer numbers and Prints
* the output on the screen.
* <p>
* <b>Note:</b> Giving proper comments in your program makes it more
* user friendly and it is assumed as a high quality code.
*
* @author Zara Ali
* @version 1.0
* @since 2014-03-31
*/
public class AddNum {
/**
* This method is used to add two integers. This is
* a the simplest form of a class method, just to
* show the usage of various javadoc Tags.
* @param numA This is the first paramter to addNum method
* @param numB This is the second parameter to addNum method
* @return int This returns sum of numA and numB.
*/
public int addNum(int numA, int numB) {
return numA + numB;
}
/**
* This is the main method which makes use of addNum method.
* @param args Unused.
* @return Nothing.
* @exception IOException On input error.
* @see IOException
*/
public static void main(String args[]) throws IOException {
AddNum obj = new AddNum();
int sum = obj.addNum(10, 20);
System.out.println("Sum of 10 and 20 is :" + sum);
}
}Teraz przetwórz powyższy plik AddNum.java za pomocą narzędzia javadoc w następujący sposób -
$ javadoc AddNum.java
Loading source file AddNum.java...
Constructing Javadoc information...
Standard Doclet version 1.7.0_51
Building tree for all the packages and classes...
Generating /AddNum.html...
AddNum.java:36: warning - @return tag cannot be used in method with void return type.
Generating /package-frame.html...
Generating /package-summary.html...
Generating /package-tree.html...
Generating /constant-values.html...
Building index for all the packages and classes...
Generating /overview-tree.html...
Generating /index-all.html...
Generating /deprecated-list.html...
Building index for all classes...
Generating /allclasses-frame.html...
Generating /allclasses-noframe.html...
Generating /index.html...
Generating /help-doc.html...
1 warning
$Całą wygenerowaną dokumentację możesz sprawdzić tutaj - AddNum . Jeśli używasz JDK 1.7, javadoc nie generuje świetnego plikustylesheet.css, dlatego sugerujemy pobranie i używanie standardowego arkusza stylów z https://docs.oracle.com/javase/7/docs/api/stylesheet.css