Javadoc-ohjeet

Julkaistu

Kaikki itse tehdyt harjoitustyön luokat dokumentoidaan Javadoc-ohjelmalla.Kaikille attribuuteille – niin tavallisille kuin vakioiduille – tulee kirjoittaa Javadoc-kommentit. Lähes kaikki metodit Javadoc-kommentoidaan. Mikäli aksessoreissa ja rakentajissa ei tehdä mitään erityistä, niin näitä metodeja ei tarvitse kommentoida.

Alla annetaan lyhyet ohjeet html-muotoisen dokumentoinnin generointiin lähdekodista ja sen Javadoc-kommenteista ja esimerkkejä.

Huomioitavaa:

  • Pelkät Javadoc-kommentit eivät riitä! Metodien sisältä pitää löytyä ”tavallisia” kommentteja.
  • Javadoc-ohjelma on hyvin monipuolinen työkalu, jolla voi halutessaan tehdä hienompiakin dokumentaatioita, mutta alla olevilla ohjeilla saa aikaiseksi harjoitustyön tarkastajille mainiosti kelpaavat tiedostot.

Javadoc-kommenttien kirjoittaminen

Javadoc-ohjelma muodostaa dokumentit /** */ -muotoisten kommenttien sisään kirjoitetusta tekstistä.

/** Tämä on Javadoc-kommentti. Alussa on kaksi asteriskia 
ja lopussa yksi asteriski. */
/* Tämä on tavallinen kommentti. Alussa ja lopussa yksi asteriski. */

Moniriviset kommentit kirjoitetaan yleensä lisäten asteriski kommentin kunkin rivin alkuun näin:

/**
 * Abstrakti Otus-luokka, joka sisältää otuksille
 * yhteiset piirteet.
 * <p>
 * Harjoitustyö, Olio-ohjelmoinnin perusteet I, kevät 201x.
 * <p>
 * @author Jorma Laurikkala (jorma.laurikkala@tuni.fi),
 * Informaatioteknologian ja viestinnän tiedekunta,
 * Tampereen yliopisto.
 */

Kommentin on sijaittava välittömästi ennen dokumentoitavaa kohdetta.

Väärinimport-lause estää luokkakuvauksen muodostamisen:

/**
 * Abstrakti Otus-luokka, joka sisältää otuksille
 * yhteiset piirteet.
 * <p>
 * Harjoitustyö, Olio-ohjelmoinnin perusteet I, kevät 201x.
 * <p>
 * @author Jorma Laurikkala (jorma.laurikkala@tuni.fi),
 * Informaatioteknologian ja viestinnän tiedekunta,
 * Tampereen yliopisto.
 */
import java.util.Random;

public abstract class Otus {
   ...
}

Oikein – kommentti välittömästi ennen luokan määrittelyä:

import java.util.Random;
/**
 * Abstrakti Otus-luokka, joka sisältää otuksille yhteiset piirteet.
 * <p>
 * Harjoitustyö, Olio-ohjelmoinnin perusteet I, kevät 201x.
 * <p>
 * @author Jorma Laurikkala (jorma.laurikkala@tuni.fi),
 * Informaatioteknologian ja viestinnän tiedekunta,
 * Tampereen yliopisto.
 */

public abstract class Otus {
   ...
}

Luokkakohtaisista kommenteista tulee löytyä harjoitustyön tekijän nimi @author-määreellä annettuina (katso yllä).

Metodien ja attribuuttien kuvaukset kirjoitetaan luokkakuvauksen tavoin juuri ennen kohdettaan:

/** Otuksen yksikäsitteinen tunnus. */
private long tunnus;
...

/** 
 * Taistellaan toisen otuksen kanssa.
 *
 * Voitto päätellään vertailemalla uusia terveydentiloja.
 *
 * @param toinen vastustaja toisesta joukkueesta.
 * @param punainen onko vastustaja punaisesta joukkueesta?
 * @return 1, jos tuli voitto, 0, jos tuli tasapeli ja -1,
 * jos toinen voitti.
 * @throws IllegalArgumentException jos parametreissa oli virhe.
 */
public int taistele(Otus toinen, boolean punainen)
throws IllegalArgumentException {
    ...
}

Metodikuvauksissa kerrotaan lyhyesti mitä metodi tekee sekä määritellään tarvittaessa parametrit ja paluuarvo. Parametri kuvataan @param-määreellä siten, että määreen perään kirjoitetaan parametrin nimi ja nimen jälkeen parametrin kuvaus. Nimi erotetaan kuvauksesta yhdellä välilyönnillä. Et voi käyttää erottimena esimerkiksi pilkkua. Paluuarvon määrittely tehdään @return-määreellä. Metodin heittämät poikkeukset annetaan @throws-määreen avulla.

Javadoc-kommentit on kirjoitettava myös yksityisille (private) luokan piirteille.

Javadoc-kommentien ja kommenttien kohteen välissä olevat tavalliset kommentit esimerkiksi alla annetulla tavalla:

/** Otuksen yksikäsitteinen tunnus. */
// Muista tavanomaista suurempi tyyppi!
private long tunnus;

eivät haittaa dokumentaation muodostamista, mutta yleensä kohteen Javadoc-kommentteja käytettäessä kommentteja ei täydennetä tavallisilla kommenteilla.

Abstraktien metodien Javadoc-kommentit ”perityvät” korvattujen metodien Javadoc-kommenteiksi automaattisesti ilman lisätoimia.

Javadoc-kommenttien muodostaminen

Javadoc-ohjelma tulee aina Java JDK -paketin mukana. Se ei ole saatavilla erikseen. Mikäli polkumäärittelyt ovat kunnossa, on Javadoc-ohjelma on ajettavissa komentoriviltä suoraan komennolla javadoc. Javadoc-ohjelma sijaitsee JDK:n bin-alihakemistossa. Polku voi olla Windows-käyttöjärjestelmässä esimerkiksi C:\Program Files (x86)\Java\jdk1.8.0\bin\javadoc.exe.

NetBeansin tapaiset kehitysvälineet kutsuvat Javadoc-ohjelmaa itse, jolloin käyttäjän ei tarvitse suorittaa ohjelmaa komentoikkunassa.

Javadoc-ohjelmaa on paras kutsua ”työhakemistostosta”, jonka välittömänä alihakemistona on harjoitustyo-pakkausten hakemisto. Tämä on sama hakemisto, josta ohjelman kääntäminen ja suorittaminen on sujuvinta komentoikkunassa.

Javadoc-ohjelmaa käytettäessä on tärkeää määritellä hakemisto, jonne sen luomat tiedostot tallennetaan, koska Javadoc sijoittaa oletusarvoisesti kaikki tuottamansa tiedostot hakemistoon, josta ohjelmaa kutsutaan. Ilman hakemistoa projektin hakemistoon tulee pahimmillaan kymmeniä tiedostoja ja hakemistoja, joiden poistaminen vie aikaa ja vaatii tarkkuutta. Hakemiston määrittelyssä on huomattava, että Javadoc-tiedostoja ei saisi pitää versionhallinnassa, koska ne voi tavukoodin tapaan muodostaa aina tarvittaessa lähdekoodista.

Javadoc-ohjelmaa kutsutaan komennolla:

javadoc -d ..\javadocs -private -author -noqualifier all -subpackages harjoitustyo -encoding utf8
  • d: dokumentaatio sijoitetaan omaan hakemistoon.Yllä Javadoc-ohjelmaa käsketään sijoittamaan tiedostonsa ylihakemistossa olevaan alihakemistoon (..\javadocs), jotta Javadoc-dokumentaatio ei jäisi versionhallinnan piirissä olevaan hakemistoon. Huomaa Windowsin tiedostonerotin. Linux- ja Mac-järjestelmissä sanottaisiin ../javadocs.
  • private: huomioi piirteiden Javadoc-kommentit näkyvyysmääreistä riippumatta.
  • author: sisällyttää @author-määreen dokumentaatioon.
  • noqualifier: jättää paramerilla all pakkauksen nimen pois kaikkien luokkien nimistä.
  • subpackages: generoi dokumentaation annetuille pakkauksille. Yllä parametrina harjoitustyo.

Komennon tuloksena javadocs-hakemistoon pitäisi syntyä Javadoc-dokumentaatio eli joukko html-muotoisia tiedostoja, joita luetaan index.html-tiedoston kautta.

Voit kohdata merkistöongelmia Javadoc-ohjelmaa käyttäessäsi. Javadoc käyttää käyttöjärjestelmän oletusmerkistöä, joka on Windowsissa usein Windows-1252 ja Mac- ja Linux-järjestelmissä tyypillisesti utf-8-koodattu Unicode-merkistö. Tilanteesta riippuen dokumentaation luominen epäonnistuu tai osa kommenttien merkeistä näkyy dokumenteista väärin, kun kommentit luodaan lähdekoodista, jonka merkistö poikkeaa järjestelmän merkistöstä.

Edellisessä komennossa oli lisäparametrina:

  • encoding: lähdekoodin merkistö. Yllä parametrina utf8.

jotta Windows-järjestelmässä voitiin generoida dokumentaatio utf-8-merkistöisestä lähdekoodista. Mac- tai Linux-järjestelmissä tätä parametria ei pitäisi tarvita.

Merkistöjä voi tarvittaessa säätää lisää parametreilla:

  • docencoding: dokumentaation merkistö.
  • charset: asettaa erikseen html-dokumentin meta-elementin charset-attribuutin arvon.

Yllä tiedostot ohjattiin versionhallinnan ulkopuolella olevaan hakemistoon. Toinen tapa välttää Javadoc-dokumentaation joutuminen versionhallintaan on .gitignore-tiedosto, johon voi määritellä myös hakemistoja.

Linkit

How to Write Doc Comments for Javadoc

Javadoc Tool Home Page