Helsingin yliopisto / Tietojenkäsittelytieteen laitos / 58160-8 Ohjelmoinnin harjoitustyö
Copyright © 1998 Jukka Manner. Tämän oppimateriaalin käyttö on sallittu vain yksityishenkilöille opiskelutarkoituksissa. Materiaalin käyttö muihin tarkoituksiin, kuten kaupallisilla tai muilla kursseilla, on kielletty.

Ohjeita javadoc:n käytöstä

(Muutettu viimeksi 2.2.1998)

Javadoc:n käyttämiseksi tarvitsevat "vain" tehdä ohjelmatekstiisi joitain merkintöjä, jotka javadoc sitten osaa kääntää suoraan HTML-sivuiksi. Javadoc tuottaa samanlaisia HTML-sivuja, kuin miltä Javan API-dokumentaatio näyttää. Käyttöperiaate on yksinkertainen:

/**
Tämä metodi vertailee käyttäjän arvausta ja palauttaa 0, 
jos arvaus oli oikea eli merkkijono "Oikea arvaus". Jos 
arvaus oli väärä, metodi palauttaa -1.

@param nimi (String) Jokin nimi
@return 0, jos arvaus oli oikea, -1 jos arvaus oli väärä
*/

public int tutkiArvaus(String nimi)
{
  if(nimi.equals("Oikea arvaus") return 0;
  else return -1;
}

Javadoc liittää kommentin aina seuraavaan luokkaan/metodiin/muuttujaan. Muuttujien esittelyssä oleellisia ovat luokan globaalit muuttujat, eivät metodien sisäiset. Ohessa on esimerkki, jossa checkURL-luokka on kirjoitettu käyttämällä javadoc:n merkintöjä. Seuraavat linkit kertovat, miltä lopullinen tulos näyttää. Sivujen kuvat löytyvät alihakemistosta images, joka on syytä kopioida myös itselleen. Tämä tarkoittaa sitä, että siihen hakemistoon, jossa sijaitsevat ohjelmakoodit, tee alihakemisto nimeltä "images", jonne kopioit kuvatiedostot. Kuvat voi suoraan kopioida hakemistopolusta /home/group/alabra/public_html/jmanner/images. Listan kuvista saat antamalla Netscapelle osoitteeksi http://www.cs.helsinki.fi/group/alabra/jmanner/images. Tästä listasta voi sitten "imuroida" itsellesi kuvat esimerkiksi pitämällä SHIFT-näppäin pohjassa ja klikkaamalla kuvatiedostoa, jolloin Netscape kysyy, että talletetaanko kuva ja mihin hakemistoon.
Javadoc kannattaa ajaa komennolla:

javadoc -private -author -version tiedosto.java
tai
javadoc -private -author -version *.java

Ylimääräiset -private, -author ja -version parametrit lisäävät tulokseen tekijän ja versionumeron sekä tiedot private-muuttujista ja metodeista (nämä eivät muuten näy). Private-muuttujen ja -metodien kanssa kannattaa miettiä, onko niiden esitteleminen tärkeää ns. API-kuvauksessa. Kannattaa kysellä ryhmän ohjaajalta:
A) Haluaako hän API-kuvauksen javadoc-muodossa?
B) Tuleeko mukaan ottaa myös private-metodit ja -muuttujat?

Itse ohjelmakoodi javadoc-komennentteineen
Lista luokista ja niiden hierarkia
checkURL-luokan esitys
Aakkosellinen hakemisto kaikista kuvatuista metodeista ja muuttujista
Javadoc:n käyttöohje (Windows) SUN:n sivuilla
Perusteellinen SUN:n ohje


Takaisin Ohjelmoinnin harjoitustyön pääsivulle.