© 1999-2003, Flemming Koch Jensen
Alle rettigheder forbeholdt
javadoc
Det er en fordel, at man har lidt kendskab til HTML - men ikke nødvendigt. Man bør have lidt erfaring med at browse rundt i JDK's API Specification i form af html-filer.

 

 

  Først og fremmest: javadoc skal ikke forveksles med DocJava. javadoc er en måde at dokumentere kildetekst, mens DocJava er et forsøg på at lære folk at lave kildetekst :-)
Der er dem der mener at kode (kildetekst) er selvdokumenterende - det er typisk folk, der ikke har skullet vedligeholde deres egen kode måneder efter de har skrevet den. Det er måske en af de sundeste oplevelser en studerende kan få, men det sker sjældent, da man naturligvis hele tiden skal videre til noget nyt, og dermed nye projekter.
Jeg skal blankt indrømme at jeg har det samme "dovne" syn på dokumentation som de fleste andre. I nu'et synes det unødvendigt og irriterende at skulle dokumentere ens programmer, men senere viser det sig at spare betydelig mere tid end det tog at lave dokumentationen. Det er lidt som med frugt og grønt, man ved godt det er sundt, men helt ærligt!
Idéen med javadoc er at programmøren skriver kommentarer i kildeteksten som senere bliver til selvstændig dokumentation. Det sker ved at man kører et program, som hedder javadoc.exe, der gennemlæser filerne og leder efter disse kommentarer. Den uddrager kommentarerne af kildeteksten og genererer en række html-filer, der kan browses med en almindelig web-browser.
De fleste har sikkert allerede stiftet bekendskab med den form for dokumentation som javadoc kan generere, da man formodes at have anvendt JDK's API Specification. Følgende viser en sådan side, for wrapper-klassen Integer:
Figur 1:
JDK's API Specification
Alt på denne side er genreret ud fra kommentarer som programmørerne ved Sun har anført i kildeteksten: Integer.java, og det er javadoc der har genereret denne html-side.

 

1. Et simpelt eksempel

Betragt følgende simple klasse og bemærk i særdeleshed kommentarerne: 
/**
 * Dette er klassen Heltal, der kan repræsentere et heltal
 */
class Heltal {
  
  /**
   * Variablen 'tal' udgør hele datakernen og indeholder
   * den heltals-værdi som instanser af denne klasse
   * repræsenterer
   */
  private int tal;
  
  /**
   * Set-konstruktor, der initialiserer værdien af 'tal'
   */
  public Heltal( int tal ) {
    set( tal );
  }
  
  /**
   * Set-metode, der sætter 'tal' til den værdi som
   * gives med som parameter
   */
  public void set( int tal ) {
    this.tal = tal;
  }
  
  /**
   * Get-metode, der returnerer værdien af 'tal'
   */
  public int get() {
    return tal;
  }
}
Eksempelet er meget simpelt og kommentarerne måske ikke strengt nødvendige, men vi vil bruge det som eksempel på, hvordan man kan skrive javadoc-kommentarer.
/** Man bemærker at blok-kommentarerne har en ekstra stjerne, idet de alle starter med "/**". javadoc vil kun beskæftige sig med blok-kommentaterer, og kun dem der har denne ekstra stjerne. Alle andre kommentarer ignoreres. Man har derved mulighed for at have almindelige kommentarer i sin kildetekst som ikke retter sig mod javadoc.
Hvis vi kører javadoc.exe på denne kildetekst får vi følgende resultat (set i en browser):
Figur 2:
Vores kommentarer er blevet javadoc
Af pladshensyn har vi her reduceret figuren til 70% af normal størrelse, men det er stadig muligt at læse teksten, selv om det kan være lidt anstrengende. Man bemærker at der også optræder en Test-klasse i øverste venstre hjørne - denne vil vi se bort fra.
Sammenligner man siden med kommentarerne i programmet ovenfor, ser man at disse nu optræder i html-filen i højre frame. I venstre frame kan man vælge mellem de klasser der i vores program; hvilket er Heltal og Test.

 

2. javadoc.exe

Hvordan genererer man rent praktisk disse html-filer; hvordan kører man javadoc.exe?
bat-file Diverse udviklingsmiljøer understøtter i en eller anden udstrækning generering af javadoc (i skrivende stund er Kawa's understøttelse ikke tilfredsstillende, så den vil vi forbigå), men jeg plejer altid at anvende javadoc.exe "manuelt". Jeg plejer at lave en bat-file i det directory som er roden i mit projekt - dvs. der hvor main.java er placeret. I dette directory vil der typisk være en række directories svarende til de packages jeg har lavet.
I bat-filen skriver jeg én linie, der udfører javadoc.exe. Ovenstående javadoc med klassen Heltal er lavet med følgende linie: 
"\program files\jdk1.3\bin\javadoc" -private -sourcepath . -d javadoc *.java
Lad os gennemgå denne linie:
Kaldet af javadoc.exe
Bemærk at dette er med fuld sti. Noget siger mig, at det ikke burde være nødvendigt at angive fuld sti, men jeg har ikke kunnet få det til at virke uden, så jeg lever med det.

-private
betyder at også private dele (instansvariable, service-metoder etc.) medtages. Default er at kun public dele medtages i de generede html-filer. Jeg sætter normalt denne option, da den javadoc jeg laver primært er til intern dokumentation (vedligeholdelses-dokumentation)
-sourcepath .
angiver hvor den kildetekst befinder sig som vi ønsker at lave javadoc på. Hvis der også indgår packages (som vi skal se senere), ændrer det ikke på hvilket directory der skal angives. Punktum betyder som bekendt "dette directory", og refererer til det directory hvor vores bat-file befinder sig.
-d javadoc
angiver hvor man ønsker de genererede html-filer skal placeres. Jeg laver altid et specielt directory til formålet (kalder det "javadoc"), som jeg placerer som et subdirectory i projektdirectoriet. Bemærk: det anførte directory skal eksistere - javadoc.exe laver det ikke selv.

*.java
er en angivelse af hvilket filer man ønsker skal indgå i javadoc'en. Vi har her valgt at alle kildetekster i projektdirectoriet skal med. Bemærk at javadoc ikke søger rekursivt ned i noget directory.
index.html Eksemplet ovenfor er meget simpelt, men det kan alligevel generere en stor mængde af html-filer, og ser man i det directory hvor de placeres, vil man måske lede søgende efter et sted at starte. "Startsiden" hedder altid index.html.
packages Det eneste vi egentlig behøver yderligere, er at kunne dokumentere packages. Betragt følgende eksempel. Bemærk vi har fjernet første del af linien, som er den samme som ovenfor: 
... -d javadoc Common Common.Settings Common.State Debug
Det nye er markeret med blåt.
Subpackages skal også listes I stedet for en angivelse af de filer vi ønsker medtaget, er der nu i stedet navnene på fire packages. Indholdet af disse fire packages vil blive medtaget i den genererede javadoc. Man bemærker at de to midterste navne er subpackages - man skal anføre samtlige packages man ønsker medtaget, også selvom de er subpackages! Det kan blive til temlig mange, og det er da heller ikke den mest intelligente beskæftigelse, i forbindelse med et projekt, at lave denne linie - den kan blive meget lang!

 

3. Tags

@ Tags bruges i kildetekstens kommentarer til at angiver bestemte former for oplysninger i javadoc. Alle tags begynder med tegnet @, f.eks. @param og @return. I dette afsnit vil vi gennemgå hvert enkelt tag.

 

@author

Man bruger dette tag til at angive hvem der har lavet kildeteksten - så ved man hvem der har skylden :-)
Man bør anvende en @author til hver forfatter; hvis der er flere
Denne tag får kun effekt i den genererede javadoc hvis man angiver -author i kommandolinien der udfører javadoc.exe.
Eksempel: 
/**
 * Dette er klassen Heltal, der kan repræsentere et heltal
 *
 * @author Flemming K. Jensen
 */
class Heltal {
Figur 3:
@author
Den røde firkant markerer, i dette og de følgende eksempler, den relevante effekt i javadoc.

 

@version

Man bruger dette tag til at angive en versionsangivelse for kildeteksten.
Denne tag får kun effekt i den generede javadoc hvis man angiver -version i kommandolinien der udfører javadoc.exe.
Eksempel: 
/**
 * Dette er klassen Heltal, der kan repræsentere et heltal
 *
 * @author Flemming K. Jensen
 * @version 1.0
 */
class Heltal {
Figur 4:
@version

 

@since

Man bruger dette tag til at angive fra og med hvilken version det pågældende har eksisteret.
Eksempel:
Følgende indikerer at klassen Heltal har eksisteret siden version 0.8 af vores applikation. 
/**
 * Dette er klassen Heltal, der kan repræsentere et heltal
 *
 * @author Flemming K. Jensen
 * @version 1.0
 * @since 0.8
 */
class Heltal {
Figur 5:
@since

 

@see

Bruges til at referere til andre steder i den genererede javadoc. Referencen vil blive en html-link, som briger én hen til beskrivelsen af det pågældende. Man kan referere til variable, metoder, klasser og packages. Hvor specifik en angivelse man skal bruge, afhænger af hvor kommentaren befinder sig.
Man kan på sædvanlig vis anvende fuld pakke-sti hvis det er nødvendigt. F.eks. angiver: 
@param common.gui.WFrame
klassen WFrame som befinder sig i package common.gui.
Såfrem en metode er overloaded, skal man angive parametrenes type, for entydigt at identificere metoden. F.eks. angiver: 
@param common.gui.WFrame#setPos( int, int )
den metode setPos, der netop tager to integers som parametre.
Bemærk, at der før metodens navn står et #. Dette tegn skal står foran alle variable og metoder, uanset om der står noget foran. # skal derfor ikke opfattes som et tegn der adskiller navnet og noget der står foran.
Eksempel: 
/**
 * Set-konstruktor, der initialiserer værdien af 'tal'
 *
 * @see #set
 */
public Heltal( int tal ) {
Figur 6:
@see
Man bemærker indikationen af, at der er tale om et html-link.

 

@param

Bruges til at beskrive en parameter. Det første ord den optræder efter @param skal være parameterens navn, dernæst følger beskrivelsen. Såfremt der er flere parametre angives disse med hver deres @param-linie.
Eksempel: 
/**
 * Set-metode, der sætter 'tal' til den værdi som
 * gives med som parameter
 *
 * @param tal angiver den værdi som datakernen skal sættes til
 */
public void set( int tal ) {
Figur 7:
@param

 

@return

Dette tag bruges til at knytte en kommentar til det der returneres.
Eksempel: 
  /**
   * Get-metode, der returnerer værdien af 'tal'
   *
   * @return Returnerer datakernens værdi
   */
  public int get() {
Figur 8:
@return

 

@throws og @exception

@throws og @exception er ækvivalente - dvs. betyder det samme. Man kan derfor frit vælge hvilken man vil bruge, og vi vil i det følgende holde os til @throws.
Man bruger @throws til at beskrive de exceptions en metode kan kaste. Man anvender en @throws-linie for hver exception.
Eksempel: 
/**
 * Denne metode indlæser et heltal og sætter datakernen til
 * den pågældende værdi
 *
 * @throws IOException kastes hvis noget går galt under indlæsningen
 */
public void readInt() throws IOException {
Figur 9:
@throws
Bemærk at javadoc selv anfører fuld pakke-sti.

 

@deprecated

Med @deprecated angiver man at noget er forældet, og skulle gerne animere læseren til at undgå fremtidig anvendelse af det.
Eksempel: 
/**
 * Denne metode indlæser et heltal og sætter datakernen til
 * den pågældende værdi
 *
 * @throws IOException kastes hvis noget går galt under indlæsningen
 * @deprecated Du bør i stedet selv indlæse værdien og sætte den
 * med set-metoden
 */
public void readInt() throws IOException {
Figur 10:
@deprecated

 

3.1 Inline tags

Inline tags, er tags man kan placere frit i de javadoc-kommentarer man laver.

 

{@link}

Fungerer på nogenlunde samme måde som @see (eller det er måske snarere omvendt!). Ved at anføre en link, kan man referere til en variabel, metode etc. på nøjagtig samme måde som for @see.
Eksempel: 
/**
 * Set-konstruktor, der initialiserer værdien af 'tal'. Denne
 * konstruktor anvender {@link #set}
 */
public Heltal( int tal ) {
Figur 11:
{@link}

 

{@docRoot}

Denne tag bruges som en slags variabel, der indeholder stien tilbage til roden af javadoc-directoriet, fra den html-file som denne javadoc-kommentar bliver placeret i.
Man kan bruge den til at referere til html-filer som man selv placerer i javadoc-directoriet.
Eksempel:
Dette eksempel forudsætter, at man ved hvordan man laver en link i html. 
/**
 * Dette er klassen Heltal, der kan repræsentere et heltal. Vedrørende
 * ophavsret se <a href="{@docRoot}/copyright.html">Copyright</a>
 *
 * @author Flemming K. Jensen
 * @version 1.0
 * @since 0.8
 */
class Heltal {
Figur 12:
{@docRoot}
I selve html-filen kommer der til at stå følgende, da begge filer befinder sig i javadoc-roden: 
<a href="./copyright.html">Copyright</a>

 

3.2 Tags vedrørende objekt-serialisering

Disse tags er kun medtaget for at jeg kan huske at de findes - jeg har ikke planer om at dokumentere dem lige med det første.

 

@serial

 

@serialData

 

@serialField

 

4. HTML

Da javadoc kommentarene alligevel ender som html, er det ikke overraskende at man rent faktisk kan bruge html-kode i sine kommentarer. Disse html-koder indsættes direkte i de html-sider javadoc genererer.
Dette er naturligvis ikke stedet for et html-kursus, men vi vil dog ikke undlade at nævne et par af muligheder.

 

4.1 Paragrafer

Hvis man har behov for at skrive større stykker af tekst - f.eks. i en indledende beskrivelse af en klasse. kan man inddele det i afsnit, eller paragrafer som det hedder i html. En paragraf angives ved at starte med et <p>, som det f.eks. er gjort i følgende eksempel 
/**
 * Dette er klassen Heltal, der kan repræsentere et heltal.
 * <p>
 * Vedrørende ophavsret se <a href="{@docRoot}/copyright.html">Copyright</a>
 * <p>
 * Det er en længere smøre at beskrive en klasse. Derfor kan det være
 * nyttigt at opdele den i flere afsnit
 *
 * @author Flemming K. Jensen
 * @version 1.0
 * @since 0.8
 */
class Heltal {
Figur 13:
Paragrafer

Havde man undladt paragraf-tegnet:

/**
 * Dette er klassen Heltal, der kan repræsentere et heltal.
 * 
 * Vedrørende ophavsret se <a href="{@docRoot}/copyright.html">Copyright</a>
 * 
 * Det er en længere smøre at beskrive en klasse. Derfor kan det være
 * nyttigt at opdele den i flere afsnit
 *
 * @author Flemming K. Jensen
 * @version 1.0
 * @since 0.8
 */
class Heltal {
  ville man i stedet have fået:
Figur 14:
Uden paragrafer

 

4.2 Kode

Hvis man ønsker at f.eks. identifiers skal stå med en font der, som i DocJava, angiver at der er tale om kode, kan man anvende html-tag'et code. 
/**
 * Set-metode, der sætter <code>tal</code> til den værdi som
 * gives med som parameter
 *
 * @param tal angiver den værdi som datakernen skal sættes til
 */
public void set( int tal ) {
Figur 15:
Kode-font
Af andre html-tags der påvirker font'ene kan nævnes <b>...</b>, der laver fed skrift og <i>...</i>, der laver skræ skrift.