2 Dokumentation

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:

• Klassediagrammer

• Beskrivelse af klasser, metoder og variabler (javadoc)

Dette kapitel beskriver hvordan, man kan udarbejde dokumentation med javadoc.

2.1 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:

/**
 * Eksempel på en kommenteret klasse.
 */
public class EnKommenteretKlasse
{
...

Ligeledes står kommentaren, der beskriver metoden, umiddelbart før erklæringen af metoden:

  /**
   * 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)
  { ...

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:

package java.util;

/**
 * The <code>Vector</code> class implements a growable array of 
 * objects. Like an array, it contains components that can be 
 * accessed using an integer index. However, the size of a 
 * <code>Vector</code> can grow or shrink as needed to accommodate 
 * adding and removing items after the <code>Vector</code> has been created.
 * <p>
 * Each vector tries to optimize storage management by maintaining a 
 * <code>capacity</code> and a <code>capacityIncrement</code>. The 
 * <code>capacity</code> is always at least as large as the vector 
 * size; it is usually larger because as components are added to the 
 * vector, the vector's storage increases in chunks the size of 
 * <code>capacityIncrement</code>. An application can increase the 
 * capacity of a vector before inserting a large number of 
 * components; this reduces the amount of incremental reallocation. 
 *
 * @since   JDK1.0
 */
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:

  ...

  /**
   * Returns the component at the specified index.
   *
   * @param   index   an index into this vector.
   * @return the component at the specified index.
   * @exception ArrayIndexOutOfBoundsException if
   *             an invalid index was given.
   * @since    JDK1.0
   */
  public final Object elementAt(int index) {
    if (index >= elementCount) {
      throw new ArrayIndexOutOfBoundsException(index + " >= " + elementCount);
    }
    try {
      return elementData[index];
    } catch (ArrayIndexOutOfBoundsException e) {
      throw new ArrayIndexOutOfBoundsException(index + " < 0");
    }
  }

  /**
   * Sets the component at the specified <code>index</code> of this 
   * vector to be the specified object. The previous component at that 
   * position is discarded. 
   * <p>
   * The index must be a value greater than or equal to <code>0</code> 
   * and less than the current size of the vector. 
   *
   * @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()
   * @since    JDK1.0
   */
  public final void setElementAt(Object obj, int index) {
    if (index >= elementCount) {
      throw new ArrayIndexOutOfBoundsException(index + " >= " + 
                 elementCount);
    }
    elementData[index] = obj;
  }

  ...

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:

  javadoc *.java

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-filer¹.

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:

<html>
  <head><title>package</title></head>
  <body>
    Dette er et eksempel på en pakkekommentar. 
    Den skal ligge i filen package.html sammen med .java-filerne den beskriver.

    @author Jacob Nordfalk
    @since 1.0
  </body>
</html>

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:
  http://java.sun.com/j2se/javadoc/writingdoccomments/

2.5 Opgaver

1. 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.

2. Hent klassen SenderActionEvent fra afsnit 4.3.5 ned til dig selv, og generér dens HTML-dokumentation.

3. Medtag henvisninger til standarddokumentationen med parameteren -link
   (beskrevet i afsnit 2.2.2, Henvise til den eksisterende javadokumentation).

2.6 Løsninger