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

.