Dokumentaatio koodikommentteina - Javadoc¶

Javadoc on dokumentaation generointiin tarkoitettu työkalu, joka tulee JDK:n mukana. Dokumentaatio kirjoitetaan määrämuotoisina kommentteina suoraan koodiin. Useat IDEt osaavat generoida dokumentaation suoraan HTML-muotoisena koodin Javadoc-kommenteista. Esimerkiksi, NetBeansissa Javadoc-dokumentaation voi luoda ajamalla Generate Javadoc klikkaamalla hiiren oikealla napilla projektin ikkunaa tai menusta Run->Generate Javadoc.

Javadoc-kommentin perusrakenne¶

Dokumentaatio kirjoitetaan koodiin Javadoc-kommenttina käyttäen standardimuotoista /* */ kommenttilohkoa siten, että lohkon avaavassa erotin sisältään ylimääräisen *-merkin eli Javadoc-kommenttilohko kirjoitetaan /** */ kommenttierottimien väliin. Kommenttilohko on rakenteeltaan seuraava. Dokumentaation teksteissä voi olla mukana HTML-tageja, kuten <p>:

Luokkatason kommenttina kirjoitetaan ennen public class Luokannimi ja import-lauseiden jälkeen kuvaus itse luokasta. Lohko tyypillisesti sisältää tagit:
- @author kertoo luokan toteuttajan tiedot
- @version ohjelman sen hetkisen version numero. Tästä erillisenä @since, joka vastaavasti kertoo, mistä versiosta lähtien kyseinen luokka on ohjelmassa ollut.

Jokaiselle metodille kirjoitetaan dokumentaatio, jossa:

Ensimmäinen kappale kuvaa dokumentoitavan metodin.
Kuvausta seuraa vaihteleva määrä metodia kuvaavia tageja. Esimerkiksi:
- @param metodin parametreja
- @return metodin paluuarvoa
- @throws kaikki metodin mahdollisesti heittämät poikkeukset

Esimerkiksi:

/**
 * Yksinkertainen kaksiulotteisen avaruuden pistettä kuvaava luokka
 * <p>
 * @author N.N.
 * @since 1.0
 */

 public class Point2D {
    /**
     * x-akselin arvo
     */
    private double x;

    /**
     * y-akselin arvo
    */
    private double y;

    /**
     * Rakennin, joka ottaa parametreina x:n ja y:n arvot
     * @param x X:n alkuarvo
     * @param y Y:n alkuarvo
     */
    public Point2D(double x, double y) {
        this.x = x;
        this.y = y;
    }

    /**
     * Rinnalle myös toinen rakennin, joka ei vaadi parametreja.
     * Toimii kuin Point2D(0, 0).
     */
    public Point2D() {
        this(0, 0);  // Rakennin voi kutsua toista rakenninta this-viitteen kautta.
    }

    /**
     * Palauttaa tilasta X:n arvon
     * @return double X:n arvo
     */
    public double getX() {
        return x;
    }

    /**
     * Asettaa X:lle uuden arvon
     * @param x Uusi arvo X:lle
     * @return ei mitään
     */
    public void setX(double x) {
        this.x = x;
    }

Ohjelmoija voi kuvailla myös pakkausta Javadoc-kommenteilla. Tämä onnistuu siten, että pakkauksen hakemistoon luodaan package-info.java-niminen tiedosto, johon kirjoitetaan omat kommentit ennen pakkausmäärettä. Esimerkiksi:

/**
 * Sisältää  Ohjelmointi 3:n JSON-harkan luokkatoteutukset.
 * <p>
 * @author N.N.
 * @since 1.0
 */
package fi.tuni.programming3;

Kaikki tagit löydät täältä.