javadoc
JDK:n dokumentoinnin mukana tulee ohjelma javadoc.exe, jolla voi generoida automaattisesti luokasta kuvauksen, joka noudattaa luokkakirjastojen kuvauksien rakennetta (kaikkine linkkeineen). Se tallentuu javan alle hakemistoon bin. Ohjelma javadoc tuottaa www-sivuston. Ohjelman käyttö on hyvin helppoa: annetaan komentoriviltä komento javadoc <java-päätteisen luokan nimi>. Esimerkiksi
javadoc -private XYPoint.java
Tämä edellyttää että suoritat komennon samassa hakemistossa, jossa on tiedosto XYPoint.java. Lisäksi Windowsin ympäristömuuttujaan path tulee asettaa polku siihen hakemistoon, jossa on tiedosto javadoc.exe.
Ohjelmakoodin sekaan kirjoitetaan tietynlaisia tageja (alkavat merkillä @), joiden perusteella javadoc ohjelma 'poimii' tietyt asiat dokumentointiin.
Huom. Jotta javadoc tuottaisi 'Field Summary':n luokkasi private-esiintymämuuttujista, tulee javadoc suorittaa optiolla private (kuten yllä). Jos esiintymämuuttuja on varustettu määreellä protected, kyseistä optiota ei tarvita.
Seuraavassa on luokka XYPoint.java,
jonka ulkoasua matkimalla sinäkin voit kirjoittaa luokkasi sellaiseen
muotoon,
että javadoc generoi siitä vaaditunlaisen kuvauksen. Sinun ei tarvitse opetella käyttämään ns. tageja
täydellisesti. Kirjoita luokkiin kommentit muodossa /**... */, jolloin
kommenttiteksti tulee automaattisesti mukaan javadocin tuottamiin
kuvauksiin. Lisää tällaiset kommentit 1) luokan alkuun ennen
class-sanaa (tässä annetaan luokan yleiskuvaus), 2) tietokenttien
eteen ja 3) metodien eteen. Kommenttitekstin ensimmäisen lauseen, joka päättyy pisteeseen,
javadoc sijoittaa Summary-osaan, esimerkiksi Method Summary-osaan, jos
kysessä on metodin kommentointi. Tähän kirjoitetaan lyhyesti ja
terävästi mitä metodi tekee viittaamalla metodin parametreihin (jos
niitä on). Sen jälkeen kirjoitetaan tarvittaessa tarkempi kuvaus
metodista ja sen mahdollinen alkuehto. Tämän ja myös Method
Summary-osassa olevan ensimmäisen lauseen javadoc sijoittaa Method
Detail-osaan (tähän päästään kun klikataan metodin nimeä Method Summary
-osiossa). Lisäksi tulee käyttää tageja @author, @param ja @return
, joiden selitykset näkyvät vain Method Detail-osiossa. Katso esimerkit yo. luokasta XYPoint.java. Huomaa
myös, että metodin palautuksen kuvaava teksti tulee kirjoittaa kahteen
kertaan: 1) Ensin kommenttiriville ja 2)
@return-tagin yhteyteen (mahdollisesti hiukan tarkemmin). Tagin @param jälkeen tulee ensin parametrin tunnus (nimi) ja sen jälkeen kerrotaan omin sanoin sen merkitys.
Vertailuoperaattorien
< jne. käytössä kommenttien sisällä on joskus ongelmia, koska niillä
on muita merkityksi
javadocin (html:n) yhteydessä. Esimerkiksi < saattaa katkaista
tekstin siihen paikkaan. Näin ollen jos ongelmia esiintyy, niin
kirjoita ne suomeksi tai seuraavasti: esimerkiksi
kirjoitelmasta
{@literal Alkuehto: 1<=v<=10}
javadoc generoi tekstin:
Alkuehto: 1<=v<=10
Voit
jättää luokasssa XYPoint.java olevat <code> ... </code> pois (tällöin näiden välissä
oleva teksti tulee samalla fontilla kuin muukin osa). Kokeile javadocin käyttöä luokan XYPoint.java avulla!
Seuraavassa on pieni esimerkki luokasta Varasto:
/** Metodi palauttaa varastosta tietyn id:n omaavan VarastoTuote-olion. Jos sitä ei löydy, palautetaan null.
@param idnro haettavan tuotteen id
@returns VarastonTuote-olion, jonka id==idnro. Jos sitä ei löydy, palautetaan null.
public VarastonTuote hae(int idnro)
*/
Tietokonetyössä
Kirjoita komentorivin komento muodossa (oletetaan että sinulla on luokat VarastonTuote.java, Varasto.java ja Testi.java):
javadoc -private
-d html VarastonTuote.java Varasto.java Testi.java
Tällöin javadocin tuottamat html-tiedostot tulevat nykyisen hakemiston alihakemistoon html (myös hakemisto luodaan). Jos parametrin -d html jättää pois, ne tulevat nykyiseen hakemistoon eli samaan hakemistoon, jossa myös myös .java-tiedostot ovat. Tästä tulee useita tiedostoja. Katso näistä ainakin tiedostot index.html, VarastonTuote.html, Varasto.html ja overview-tree.html kaksoisklikkaamalla nimeä. Tiedostosta index.html on pääsy kaikkien luokkien kuvauksiin. Lähetä koko hakemisto html (zipattuna) dokumentin mukana.
javadocin voi asentaa myös JCreatorin yhteyteen. Menettele kuten tässä neuvotaan eli suorita em. linkin kohdan javadoc tools kohdat 1-8, mutta kirjoita arguments kohtaan -private VarastonTuote.java Varasto.java. Command kohdassa on valmiina polku hakemistoon, jossa javadoc.exe sijaitsee. Sen jälkeen JCreatorissa voidaan suorittaa javadoc valitsemalla Tools/javadoc
DrJavassa voi suorittaa javadocin suoraan valitsemalla: Tools/javadoc. Tosin tämä ei tuota vaadittuja private-tietokenttiä.
NetBeans: ks. esim. https://edu.netbeans.org/quicktour/javadoc.html
Suppeat selitykset Javadocin tageista on täällä ja tarkat selitykset voit lukea esim. sivuilta http://www.oracle.com/technetwork/java/javase/documentation/index-137868.html#tag
.