Att dokumentera javaprogram enligt Javadoc

Javadoc är ett verktyg som utvecklats av Sun Microsystems för att på ett standardiserat sätt skapa dokumentation till javaprogram (projekt). Javadoc är ett program som genererar dokumentation i HTML-format utifrån kommentarer i javakoden som följer speciella regler. Man måste använda en speciell notation för att indikera att det rör sig om just det innehåll som ska tolkas som dokumentation. Delarna utgörs av javakommentarer av typen: 
 /** 
 * ... bla, bla
 */
Dessa kan innehålla t.ex. @param ... och @return ....

Ett exempel

Notera blocken av kommentarer som finns före varje metod. 
/** 
 * Represents a dice with a specified number of sides
 */
public class Dice {                    
   private int numberOfSides;         
   private int value;

   /**
    * Constructs a standard dice with 6 sides
    */
   public Dice() {
      this(6);                        
   }

   /**
    * Constructs a dice with a specified number of sides
    * @param numberOfSides number of sides
    * @throws RuntimeException if non positive number of sides
    */
   public Dice(int numberOfSides) {
      if (numberOfSides<=0) {         
         throw new RuntimeException("Negative number of sides");
      }
      this.numberOfSides = numberOfSides;
      roll();			  
   }

   /**
    * Makes a random change of the value
    * @return the new value
    */
   public int roll() {                    
      return value = (int)(Math.random()*numberOfSides) + 1;
   }

   /**
    * To access the value
    * @return the current value
    */
   public int getValue() {         
      return value;
   }

   /**
    * A small test program
    */
   public static void main(String[] args) {
      Dice d = new Dice(13);        
      for (int i = 1; i <= 10; i++) {               
          System.out.println(d.roll());
      }			     
      System.out.println("Test run completed");
   }
}
Om klassen är kompilerad så ser det ut så här i DrJava. Om man nu klickar på Javadoc (längst uppe till höger i DrJava) kommer programmet Javadoc starta. Programmet frågar efter vilken mapp som resultatet skall sparas. Därefter kommer dokumentationen att skapas i form av en HTML-fil som dessutom kommer att visas av den webbläsare man använder. Så här ser dokumentationsfilen ut.

Notera det som syns i dokumentationsfilen och jämför med hur javafilen ser ut.

Om du vill testa själv att skapa dokumentationen så finns klassen Dice finns att hämta här.

Valid CSS!