Java - Documentatie Opmerkingen
De Java-taal ondersteunt drie soorten opmerkingen −
| Zr.nr. | Opmerking en beschrijving |
|---|---|
| 1 | /* tekst */ De compiler negeert alles van /* tot */. |
| 2 | //tekst De compiler negeert alles van // tot het einde van de regel. |
| 3 | /** documentatie */ Dit is een commentaar op documentatie en heet in het algemeen doc commentaar . De JDK javadoc tool gebruikt doc-opmerkingen bij het voorbereiden van automatisch gegenereerde documentatie. |
Dit hoofdstuk gaat over het uitleggen van Javadoc. We zullen zien hoe we Javadoc kunnen gebruiken om nuttige documentatie voor Java-code te genereren.
Wat is Javadoc?
Javadoc is een tool die bij JDK wordt geleverd en wordt gebruikt voor het genereren van Java-codedocumentatie in HTML-indeling van Java-broncode, waarvoor documentatie in een vooraf gedefinieerde indeling vereist is.
Hieronder volgt een eenvoudig voorbeeld waarbij de regels binnen /*….*/ Java-commentaar met meerdere regels zijn. Evenzo is de regel die voorafgaat aan // een Java-commentaar van één regel.
Voorbeeld
/**
* 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!");
}
}
U kunt de vereiste HTML-tags opnemen in het beschrijvingsgedeelte. Het volgende voorbeeld maakt bijvoorbeeld gebruik van
....
voor de kop enis gebruikt voor het maken van een alinea-einde −
Voorbeeld
/**
* <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!");
}
}
De javadoc-tags
De javadoc-tool herkent de volgende tags −
| Tag | Beschrijving | Syntaxis |
|---|---|---|
| @author | Voegt de auteur van een klas toe. | @auteur naam-tekst |
| {@code} | Geeft tekst weer in codelettertype zonder de tekst te interpreteren als HTML-opmaak of geneste javadoc-tags. | {@code text} |
| {@docRoot} | Vertegenwoordigt het relatieve pad naar de hoofdmap van het gegenereerde document vanaf elke gegenereerde pagina. | {@docRoot} |
| @verouderd | Voegt een opmerking toe die aangeeft dat deze API niet langer mag worden gebruikt. | @deprecated verouderdetext |
| @uitzondering | Voegt een Throws . toe subkop naar de gegenereerde documentatie, met de klassenaam en beschrijvingstekst. | @exception class-name description |
| {@inheritDoc} | Erft een opmerking van de dichtstbijzijnde overerfbare klasse of implementeerbare interface. | Erft een opmerking van de directe superklasse. |
| {@link} | Voegt een in-line link in met het zichtbare tekstlabel dat verwijst naar de documentatie voor het gespecificeerde pakket, de opgegeven klasse of de naam van het lid van een klasse waarnaar wordt verwezen. | {@link package.class#member label} |
| {@linkplain} | Identiek aan {@link}, behalve dat het label van de link wordt weergegeven in platte tekst dan in het codelettertype. | {@linkplain package.class#member label} |
| @param | Voegt een parameter toe met de opgegeven parameternaam gevolgd door de opgegeven beschrijving aan de sectie "Parameters". | @param parameternaam beschrijving |
| @return | Voegt een sectie 'Retouren' toe met de beschrijvingstekst. | @return beschrijving |
| @see | Voegt een kop 'Zie ook' toe met een link of tekst die naar een verwijzing verwijst. | @zie referentie |
| @serial | Gebruikt in de doc-opmerking voor een standaard serialiseerbaar veld. | @serial field-description | inclusief | uitsluiten |
| @serialData | Documenteert de gegevens die zijn geschreven door de methode writeObject( ) of writeExternal( ). | @serialData data-description |
| @serialField | Documenteert een ObjectStreamField-component. | @serialField veldnaam veldtype veldbeschrijving |
| @sinds | Voegt een kop "Sinds" toe met de opgegeven sinds-tekst aan de gegenereerde documentatie. | @sinds release |
| @throws | De tags @throws en @exception zijn synoniemen. | @throws class-name description |
| {@value} | Als {@value} wordt gebruikt in de doc-opmerking van een statisch veld, wordt de waarde van die constante weergegeven. | {@value package.class#field} |
| @versie | Voegt een "Versie" subkop met de gespecificeerde versie-tekst toe aan de gegenereerde documenten wanneer de -version optie wordt gebruikt. | @version version-text |
Voorbeeld
Het volgende programma gebruikt enkele van de belangrijke tags die beschikbaar zijn voor opmerkingen over documentatie. U kunt andere tags gebruiken op basis van uw vereisten.
De documentatie over de AddNum-klasse wordt geproduceerd in het HTML-bestand AddNum.html, maar tegelijkertijd wordt er ook een hoofdbestand gemaakt met de naam 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);
}
}
Verwerk nu het bovenstaande AddNum.java-bestand met het javadoc-hulpprogramma als volgt −
$ 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 $
U kunt alle gegenereerde documentatie hier controleren − AddNum. Als u JDK 1.7 gebruikt, genereert javadoc geen geweldige stylesheet.css , dus we raden aan om een standaard stylesheet te downloaden en te gebruiken van https://docs.oracle.com/javase/7/docs/api/stylesheet.css
Java