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;
    }

Dokumentaation luomiseksi pakkaukselle tulee kirjoittaa pakkauksen kansioon erilliseen tiedostoon package-info.java, johon kirjoitetaan ennen pakkauksen määritystä dokumentaatiolohko, johon kirjoitetaan kuvaus pakkauksesta. Esim.

/**
 * 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ä.

Palautusta lähetetään...