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 ja esimerkkejä.
Huomioitavaa:
- Pelkät Javadoc-kommentit eivät riitä! Koodista 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öntarkastajille 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. */
Kommentin on sijaittava välittömästi ennen dokumentoitavaa kohdetta.
Väärin – import-lause estää luokkakuvauksen muodostamisen:
/** * Abstrakti Otus-luokka, joka sisältää otuksille * yhteiset piirteet. * <p> * Harjoitustyö, Olio-ohjelmoinnin perusteet, kevät 2010. * <p> * @author Jorma Laurikkala (jorma.laurikkala@uta.fi), * Luonnontieteiden 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, kevät 2010.
* <p>
* @author Jorma Laurikkala (jorma.laurikkala@uta.fi),
* Luonnontieteiden 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. 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.
Solmu– ja LinkitettyLista-luokat sekä AbstraktiLista-yliluokka ja Lista-rajapinta on dokumentoitu esimerkinomaisesti. Harjoitustyössä tulisi siis olla suunnilleen samantasoinen Javadoc-dokumentaatio kuin edellä mainituissa luokissa ja rajapinnassa. Huomaa, että LinkitettyLista– ja AbstraktiLista-luokissa osa kommenteista on ”periytetty” @inheritDoc-määreellä Lista-rajapinnasta, jotta samoja kommentteja ei ole tarvinnut kirjoittaa uudelleen näihin luokkiin. Korvattujen metodien Javadoc-kommentit kopioituvat myös ilman lisätoimia, mutta @inheritDoc-määreellä kommentteja voi tarvittaessa tarkentaa.
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-paketin 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 hakemistossa, jossa on ajoluokka Oope2081HT ja jonka välittömänä alihakemistona on oope2018ht-pakkausten hakemisto. Tämä on sama hakemisto, josta ohjelman kääntäminen ja suorittaminen on sujuvinta komentoikkunassa.
Javadoc-ohjelmaa kutsutaan komennolla:
javadoc Oope2018HT.java -d javadocs -private -author -noqualifier all -subpackages oope2018ht
Ohjelman parametrit määrittelevät seuraavaa:
- d: dokumentaatio sijoitetaan omaan hakemistoon. Yllä parametrina javadoc.
- 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 oope2018ht.
Säädä tarvittaessa NetBeansin tai vastaavan kehitysohjelman asetuksia siten, että kommentit muodostuvat yllä määritellyllä tavalla.
Komennon tuloksena javadocs-hakemistoon pitäisi syntyä Javadoc-dokumentaatio eli joukko HTML-muotoisia tiedostoja, joita luetaan index.html-tiedoston kautta.
Voit kohdata merkistöongelmia myös 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ä. Vain yhdessä järjestelmässä työskenneltäessä merkistöongelma selviää helpoiten vaihtamalla väärässä merkistössä olevan koodin merkistö järjestelmän merkistöksi. Esimerkiksi Windowsissa vahingossa UTF-8-merkistöllä tehty tiedosto on helppo muuttaa esimerkiksi Notepad++-editorilla Windowsin merkistöön.
Eri järjestelmiä käytettäessä Javadoc-ohjelma täytyy ohjata parametrien avulla oikean merkistön pariin. Esimerkiksi Windows-järjestelmässä voi tuottaa UTF-8-merkistöisestä lähdekoodista UTF-8-merkistöisen dokumentaation komennolla:
javadoc Oope2018HT.java -d javadocs -private -author -noqualifier all -subpackages oope2018ht -encoding utf8 -docencoding utf8 -charset utf8
Ohjelman parametrit määrittelevät seuraavaa:
- encoding: lähdekoodin merkistö. Yllä parametrina utf8.
- docencoding: dokumentaation merkistö. Yllä parametrina utf8.
- charset: asettaa HTML-dokumentin meta-elementin charset-attribuutin arvon. Tämä attribuutti kertoo selaimelle missä merkistössä dokumentti on. Yllä parametrina utf8.
Linkit
Solmu-, LinkitettyLista ja AbstraktiLista-luokista ja Lista-rajapinnasta generoitu dokumentaatio.