Javadoc
Javadoc is een documentatiegenerator uit de Java Development Kit (JDK), waarmee HTML-pagina's met API-documentatie worden gemaakt. API documentatie wordt gebruikt om een programma te beschrijven, het geeft aan in welke packages en klassen een Java programma is ingedeeld, welke variabelen en methoden er zijn, en wat ze precies doen in het programma.
Javadoc is de industriestandaard voor het documenteren van Java programma's, en de meeste Integrated Development Environments (IDE) zullen automatisch javadoc documentatie genereren.
Programmeurs kunnen met bepaalde commentaartekens en Javadoc-elementen onderdelen uitgebreider beschrijven en extra verwijzingen laten genereren door javadoc:
| Element | Beschrijving |
|---|---|
| @author | Naam van de programmeur |
| @deprecated | Markeert de methode als verouderd (deprecated). |
| @exception | Geeft aan wanneer een uitzondering (exception) veroorzaakt kan worden (thrown) door een methode — zie ook @throws. |
| @param | Definieert een parameter van een methode. Verplicht voor iedere parameter. |
| @return | Documenteert de teruggegeven waarde. Moet niet gebruikt worden voor methoden die een void teruggeven. |
| @returns | Een synoniem voor @return. |
| @see | Geeft een verwijzing aan naar een andere methode of klasse. |
| @since | Geeft aan wanneer een methode toegevoegd is aan de klasse. |
| @throws | Documenteert de veroorzaakte uitzondering (thrown exception). Een synoniem voor @exception, geïntroduceerd in Javadoc 1.2. |
| @version | Geeft het versienummer van een methode of klasse aan. |
Een voorbeeld van het gebruik:
/**
* Geeft de naam van de persoon
* @author John Doe
* @param id Identificatienummer van persoon
* @return Naam van de gevonden persoon
* @since 01-01-2000
* @version 1.0
* @exception PersonNotFoundException Wanneer er geen persoon met de gegeven identifier kan worden gevonden
*/
String getName(int id) throws PersonNotFoundException
{
...
}