Javadoc exempel Stack.java


Klasser bör dokumenteras. För javaklasser finns ett program, javadoc, som hämtar information ur javaprogrammet och producerar ett html-dokument som kan läsas med en WWW-bläddrare som t ex Netscape. I programmet kan man lägga in särskilda kommentarer som reproduceras i dokumentet.

Kommentarer kan skrivas på två sätt.

För att kommentarer skall inkluderas av javadoc skall man använda den senare modellen och låta /* följas av ytterligare asterisk. För att göra kommentarens utsträckning tydligare får man använda en asterisk som första ickeblanka tecken på mellanliggande kommentarrader. Det finns ett antal speciella strängar som inleds med @, som javadoc hanterar speciellt. Programmet anropas med namnet på Java-filen som argument. Se nedanstående exempel:

// Här finns ett exempel på hur ni skall dokumentera era klasser, metoder och variabler. 



/**
 * The Stack class represents a
 * last-in-first-out (LIFO) stack of object.
 * @author Lennart Andersson
 * @version 1997-12-05
 */

public class Stack {
  private Node top;


  /**
   * Create an empty stack.
   */
  public Stack () {
  }


  /**
   * Push item onto the top of this stack.
   * @param item the item to be pushed onto this stack.
   */
  public void push (Object item) {
     top= new Node(item, top);
  } // push


  /**
   * Inspects the item at the top of this stack.
   * @return the item at the top of this stack.
   * @exception RuntimeException if this stack is empty.
   */
  public Object top() {
     if (top!=null) {
          return top.item;
     } else {
          throw new RuntimeException("Stack.top: stack empty");
     } // else
  } // top

  /**
   * Removes the item at the top of this stack.
   * @exception RuntimeException if this stack is empty.
   */
  public void pop() {
     if (top!=null) {
        top=top.next;
     } else {
        throw new RuntimeException("Stack.top: stack empty");
     } // else
  } // pop

  /**
   * Tests if this stack is empty.
   * @return true if this stack is empty, otherwise false.
   */
  public boolean isEmpty() {
     return top==null;
  } // isEmpty

} // Stack


Normalt är det viktigare att beskriva vad en klass och dess metoder gör än hur.