javabog.dk - - Dokumentation
2.1 Javadoc 46
2.1.1 API-dokumentation 46
2.1.2 At dokumentere med javadoc 47
2.1.3 Simpelt eksempel 47
2.1.4 Større eksempel: Vector-klassen 48
2.1.5 Oversigter 49
2.2 Kørsel af javadoc 50
2.2.1 Simpel brug 50
2.2.2 Henvise til den eksisterende javadokumentation 50
2.3 Appendiks 51
2.3.1 Parametre til javadoc 51
2.3.2 Koder tilgængelige i javadoc 52
2.3.3 Pakkekommentarer 52
2.4 Videre læsning 53
2.5 Opgaver 53
2.6 Løsninger 54
En overfladisk forståelse af dette kapitel er en fordel i resten af bogen.
Tak til Jonas Kongslund og Skåne Sjælland Linux-brugergruppe, der har doneret udgangspunktet til kapitlet, fra http://www.linuxbog.dk/java/bog/.
Dokumentation er et vigtigt aspekt af ethvert programudviklingsprojekt. Dokumentationen kan have mange former og modtagere. Det kan f.eks. være:
Henvendt til slutbrugeren og vejlede i, hvordan programmet bruges (brugervejledning)
Henvendt til driftsafdelingen/systemadministratoren og vejlede i:
Udseende og fortolkning af logfiler
Hvordan programmet skal bringes til at fungere igen, hvis det stopper
Hvilke forudsætninger der skal gælde (f.eks. hvilke andre programmer der skal være installeret og i hvilke versioner), for at programmet fungerer
Hvordan programmet installeres og konfigureres
Henvendt til en anden programmør som dokumentation af et færdigt program, som programmøren skal vedligeholde:
Testtilfælde (inddata og forventede uddata)
Analyse- og designdokumenter, herunder klassediagrammer
Beskrivelse af klasser, metoder og variabler (javadoc)
Henvendt til en anden programmør som dokumentation af et API-programbibliotek som skal bruges fra et program:
Dette kapitel beskriver hvordan, man kan udarbejde dokumentation med javadoc.
Javadoc er en beskrivelse af alle pakker, klasser, interfaces, metoder og variabler, samt eventuelt vejledning i, hvordan de bør bruges. Den kan genereres ud fra kommentarer i kildeteksten ved hjælp af et udviklingsværktøj eller ved at køre javadoc fra kommandolinjen (DOS-prompten).
2.1.1 API-dokumentation
Et API (Application Programming Interface) er et sæt klasser, som man kan bruge i sit program, og som letter programmørens arbejde. F.eks. giver JDBC-klasserne let adgang til forskellige databaser på en ensartet måde.
Dokumentationen af et API kan opfattes som en kontrakt mellem den programmør, der har implementeret (skrevet) API'et (leverandøren), og den programmør, der vil bruge API'et (klienten).
Hvis leverandøren f.eks. lover at metoden double sqr(int tal) returnerer kvadratroden af tallet, når det ikke er negativt, så ved klienten, at uanset hvordan metoden er implementeret, så vil den altid returnere kvadratroden med så stor præcision, som returtypen tillader.
Hvis returværdien viser sig at være forkert i nogle tilfælde, så har leverandøren brudt kontrakten, og metoden er implementeret forkert.
Hvis klienten kalder metoden med et negativt tal, er der også tale om kontraktbrud. Kontraktbrud kan enten resultere i en undtagelse, eller at resultatet ikke er veldefineret.
2.1.2 At dokumentere med javadoc
Kommentarer i kildeteksten, der starter med /** og slutter med */, opfattes som specielle javadoc-kommentarer. Både interfaces, klasser, variabler, konstruktører og metoder kan dokumenteres ved at lave en javadoc-kommentar umiddelbart før det, der skal dokumenteres.
2.1.3 Simpelt eksempel
Her er en klasse med en metode. Begge er kommenteret med javadoc-kommentarer:
* Eksempel på en kommenteret klasse.
public class EnKommenteretKlasse
* Et eksempel på en metode. Metoden tjener
* til at vise hvordan javadoc virker.
* @param enStreng strengen
* @param etTal tallet
* @return strengen og tallet sat sammen
public String enMetode(String enStreng,
int etTal)
return enStreng+etTal;
Bemærk, hvordan kommentaren, der beskriver klassen, står umiddelbart før erklæringen af klassen:
Ligeledes står kommentaren, der beskriver metoden, umiddelbart før erklæringen af metoden:
Her er de specielle javadoc-koder @param og @return anvendt i javadoc-kommentaren (En liste over javadoc-koder kan findes i afsnit 2.3.2).
Nu kan vi generere en HTML-fil (med filnavnet EnKommenteretKlasse.html) ved at udføre kommandoen:
javadoc EnKommenteretKlasse.java
Resultatet er den velkendte dokumentation for klasser (vist til højre).
2.1.4 Større eksempel: Vector-klassen
Da Vector-klassen er velkendt for de fleste, er den valgt til at illustrere sammenhængen mellem javadoc-kommentarerne i kildetekst og den genererede HTML-dokumentation:
* The <code>Vector</code> class implements a growable array of
* <code>Vector</code> can grow or shrink as needed to accommodate
* adding and removing items after the <code>Vector</code> has been created.
* Each vector tries to optimize storage management by maintaining a
* <code>capacity</code> is always at least as large as the vector
* vector, the vector's storage increases in chunks the size of
* capacity of a vector before inserting a large number of
* components; this reduces the amount of incremental reallocation.
public class Vector implements Cloneable, java.io.Serializable
... (nogle metoder og variabler)
Ud fra denne del af kildeteksten genererer javadoc HTML-koden med den overordnede beskrivelse af klassen:
Bemærk, hvordan der bruges HTML-koder i kildeteksten til at fremhæve blandt andet klassenavne for at øge læsevenligheden af den genererede dokumentation.
Fortsætter vi i kildeteksten til Vector (der findes samlet i afsnit 1.6.8), kan vi se, hvordan javadoc genererer HTML-kode (vist til højre) ud fra beskrivelsen af metoderne og specielle javadoc-koder (beskrevet i afsnit 2.3.2) som @param, @return, @exception, @since og @see:
* @param   index   an index into this vector.
* @return the component at the specified index.
*             an invalid index was given.
* @since    JDK1.0
public final Object elementAt(int index) {
throw new ArrayIndexOutOfBoundsException(index + " < 0");
* @param   obj what the component is to be set to.
* @param   index the specified index.
* @exception ArrayIndexOutOfBoundsException if the index was invalid.
* @see    java.util.Vector#size()
public final void setElementAt(Object obj, int index) {
2.1.5 Oversigter
Mellem den overordnede klassebeskrivelse og denne (detaljerede) beskrivelse af metoderne findes en oversigt over variabler, konstruktører og metoder.
I oversigter står generelt kun teksten indtil det første punktum i javadoc-kommentarerne. F.eks. står der i oversigten over metoder ('method summary') for setElementAt() følgende:
Resten af javadoc-kommentaren (efter punktummet) er altså udeladt i oversigten (sammenlign med kommentaren til setElementAt() ovenfor).
Det er derfor smart at lade den første sætning i hver kommentar være beskrivende nok til, at man hurtigt får en idé om, hvad eksempelvis en metode gør.
2.2 Kørsel af javadoc
Javadoc kan køres fra kommandolinjen, men er også indbygget i de fleste java-udviklingsmiljøer (kunne f.eks. være under "Tools" / "Generate Javadoc").
I det følgende vil vi koncentrere os om kørsel fra kommandolinjen. Det forudsættes, at læseren er nogenlunde bekendt med kommandolinjen (f.eks. ved, hvordan man skifter katalog).
Får du fejlen "javadoc: Forkert kommando eller filnavn", når du skriver 'javadoc' på kommandolinjen, er det, fordi java-udviklingskittet (JDK'en) ikke er med i stien. Du kan da:
Enten skrive den fulde sti, f.eks.:
/usr/local/jdk1.4/bin/javadoc (UNIX/Linux) eller
\jdk1.4\bin\javadoc (DOS/Windows)
Eller ændre stien (PATH-variablen), f.eks.:
export PATH=/usr/local/jdk1.4/bin/:$PATH (UNIX/Linux) eller
set PATH=\jdk1.4\bin\;%PATH% (DOS/Windows)
2.2.1 Simpel brug
Det simpleste er at skifte katalog til der, hvor .java-filerne er og skrive:
Herefter vil HTML-filerne blive genereret og ligge i det aktuelle katalog (har man nogen pakker, vil HTML-filerne ligge i de tilsvarende underkataloger).
Ønsker man, at de genererede HTML-filer skal lægges andetsteds, kan det specificeres med parameteren -d og stien, f.eks.:
javadoc -d /tmp/javadoc-filer *.java
hvorefter HTML'en lægges i kataloget /tmp/javadoc-filer1.
Parameteren '*.java' tager alle de .java-filer, der findes i det aktuelle katalog.
Hvis man arbejder med pakker, kan man også blot nævne pakkens navn. Har man f.eks. defineret pakken 'vp', kan man skrive (fra kilde-rodkataloget, dvs. overkataloget til 'vp')
javadoc vp
hvorefter der bliver genereret dokumentation for alle vp-pakkens klasser (alle .java-filer i det tilsvarende underkatalog) og eventuelle underpakker.
De vigtigste kommandolinje-parametre til javadoc er beskrevet i afsnit 2.3.1.
2.2.2 Henvise til den eksisterende javadokumentation
Ofte (faktisk altid) vil ens metoder returnere (eller have som parametre) nogle objekter fra standardbiblioteket. I eksemplet med EnKommenteretKlasse tager metoden en streng, men klassen java.lang.String har vi ikke selv lavet, og derfor er der ikke nogen henvisning til dokumentation for den, da javadoc som udgangspunkt genererer HTML-dokumentation, der ikke henviser til eksterne kilder.
Det kan dog laves om ved at fortælle javadoc, hvor den eksterne dokumentation befinder sig, med parameteren -link, f.eks.:
javadoc -link http://java.sun.com/j2se/1.3/docs/api/ *.java
Herefter vil der blive henvist til javas standarddokumentation på Suns hjemmeside, hver gang javadoc møder returtyper, parametertyper, superklasser/implementerede interfaces og kastede undtagelser fra standardbiblioteket.
2.3 Appendiks
2.3.1 Parametre til javadoc
Den generelle brug af javadoc er:
javadoc [tilvalg] [pakkenavne] [kildetekstfiler] [klassenavne]
hvor de vigtigste tilvalg (flag) er beskrevet herunder:
Tilvalg til javadoc. En fuld liste over tilvalg fås ved at skrive 'javadoc' fra kommandolinjen.
-public Medtag kun ting (klasser, interfaces, variabler, metoder) erklæret public
-protected Medtag kun ting erklæret protected eller public (standardindstilling)
-package Medtag alt undtagen ting erklæret private
-private Medtag alt
-sourcepath <sti-liste> Angiv, hvor .java-filer med kildeteksten kan findes
-classpath <sti-liste> Angiv, hvor binære .class-filer i øvrigt kan findes
-d <directory> Destinationskatalog for de genererede HTML-filer
-use Medtag oversigter over, hvor klasser og pakker bruges henne
-version Medtag @version-afsnit
-author Medtag @author-afsnit
-link <url> Opret eksterne henvisninger til eksisterende javadoc på <url>
-nodeprecated Ignorér @deprecated (frarådede metoder/klasser)
-nosince Ignorer @since (hvornår noget blev indført i programmet)
-nodeprecatedlist Opret ikke liste over frarådede ting
-notree Opret ikke et træ over klassehierarkiet
-noindex Opret ikke en indholdsfortegnelse over klasserne
-nohelp Opret ikke en henvisning til hjælp
-nonavbar Opret ikke en navigations-bjælke
2.3.2 Koder tilgængelige i javadoc
I eksemplet er der knyttet Javadoc-kommentarer til metoder og klassevariabler samt klassen selv. I de fleste af kommentarerne anvendes der Javadoc-koder.
@author angiver ophavsmanden til klassen. Det er muligt at angive flere @author-koder på separate linjer, såfremt der er flere ophavsmænd.
@version, der er obligatorisk, angiver versionsnummeret og er for Javadoc-kommentarernes vedkommende beregnet til klasser og interfaces. Versionsnummeret har ikke nogen speciel betydning og kan derfor være hvad som helst.
@since angiver, fra hvilken version tilføjelsen fandt sted, og kan bruges overalt. Versionsnummeret har ikke nogen speciel betydning og kan derfor være hvad som helst.
@param beskriver en parameter og er beregnet til metoder og konstruktører. Først angives parameterens navn og dernæst beskrivelsen.
@return beskriver returværdien af en metode.
@exception gør det samme som @throws.
@throws beskriver en undtagelse og er beregnet til metoder og konstruktører. Der kan være flere @throws-koder. Efter hver @throws skal stå klassenavnet på undtagelsen og en beskrivelse af hvornår denne undtagelse opstår.
@see henviser til en pakke, interface, klasse, variabel, konstruktør eller metode. En af de mulige henvisningsformer er @see pakkenavn.klassenavn#medlem, hvor medlem kan være et metodenavn med parametertyper eller et variabelnavn. Pakkenavn og klassenavn kan udelades, hvis der henvises til en metode eller variabel indenfor samme klasse.
@deprecated kan bruges overalt og angiver, at en metode (eller en variabel, klasse, interface, ...) ikke længere bør anvendes (og muligvis vil udgå i en senere version). Det er anbefalelsesværdigt at henvise til et alternativ ved hjælp af @see.
@serial kan bruges til at komme med bemærkninger om serialiseringen af klassen.
2.3.3 Pakkekommentarer
En pakkekommentar laves ved at oprette en HTML-fil kaldet package.html, der placeres i pakkens katalog. Hvis pakken f.eks. hedder 'vp', så placeres filen i underkataloget 'vp' (der hvor .java-filerne også ligger), hvorefter javadoc sørger for at medtage filen.
Her er et eksempel på en pakkekommentar:
<head><title>package</title></head>
Dette er et eksempel på en pakkekommentar.
Den skal ligge i filen package.html sammen med .java-filerne den beskriver.
@author Jacob Nordfalk
Javadoc bruger kun det, der står mellem <body> og </body>, så titlen kan være hvad som helst. Det er muligt at anvende visse Javadoc-koder i pakkekommentarer, nemlig @author, @version, @since, @deprecated og @see.
Bemærk, at HTML-filen med pakkekommentarer ikke må indeholde /** ... */, og at en linje ikke må starte med *.
2.4 Videre læsning
På UNIX/Linux-systemer giver 'man javadoc' en meget udførlig vejledning
Javadoc-værktøjets hjemmeside, http://java.sun.com/j2se/javadoc/
Råd og vejledning til god praksis omkring at skrive javadoc-kommentarer:
2.5 Opgaver
Kig i kildeteksten til Vector-klassen (den kan findes i afsnit 1.6.8 eller i din java-installation, ofte i filen src.zip), og studér metoderne insertElementAt() og toArray().
Sammenlign med javadokumentationen (hjælpen) til Vector, og find ud af, hvad koderne @param, @exception, @see, @return og @since gør.
Hent klassen SenderActionEvent fra afsnit 4.3.5 ned til dig selv, og generér dens HTML-dokumentation.
Medtag henvisninger til standarddokumentationen med parameteren -link
(beskrevet i afsnit 2.2.2, Henvise til den eksisterende javadokumentation).
2.6 Løsninger
1Under UNIX/Linux. Under DOS/Windows skriver man f.eks. c:\tmp\javadoc-filer