: Javadokumenttien kirjoittaminen - JavaDoc

JavaDoc

Osa ohjelmiston dokumentointia on lähdekoodin API-kuvaus.  Javassa lähdekoodi dokumentoidaan käyttäen JavaDoc-työkalua.  Dokumentointi on kuin kommenttien kirjoittamista, mutta erityisillä avainsanoilla.  JavaDoc työkalu, jota voi käyttää suoraan NetBeanssin valikoista tekee kaikesta lähdekoodidokumentoinnista automaattisesti HTML-sivun.

Seuraava metodi on kommentoitu vapaamuotoisesti.  Kommentista käy ilmi mitä metodi tekee, mutta muotoiltua dokumentointisivua siitä ei saa tehtyä automaattisesti.

/* 
 * kertoo kuinka todennäköistä onnistuminen on käyttäjän syötteellä.
 * huom! käyttää yläluokan metodia ja palauttaa arvon vähennettynä kalibroinnilla
 */
public int onnistumistodennakoisyys(int syote) {
    int tn = super.laskeTn(syote) - this.kalibrointi;
    return tn;
}

JavaDoc-dokumentoinnilla sama kuvaus olisi seuraavaa:

/**
 * Metodi kertoo mikä on onnistumistodennäköisyys syöteluvulla
 * ottaen huomioon olion konstruktorissa asetetun kalibrointiarvon
 *
 * @param   syote   Käyttäjän antama syöte
 * 
 * @return todennäköisyys kalibroituna
 */
public int onnistumistodennakoisyys(int syote) {
    int tn = super.laskeTn(syote) - this.kalibrointi;
    return tn;
}

JavaDocin @param jne. avainsanoja ei onneksi tarvitse opetella ulkoa, koska NetBeans osaa täydentää myös JavaDoc-dokumentointia.  Oletusarvoisesti private & package -näkyvyydellä olevat metodit eivät tule dokumentointiin.  Tässä projektissa dokumentoimme kuitenkin kaikki.

Tehtävä:

  1. Klikkaa projektin juuri hiiren oikealla ja valitse Properties.  Tämän jälkeen valitse Build -> Documenting jonka jälkeen täppää Include Private and Package Private Members.
  2. Tee jollekkin metodille esimerkin mukainen dokumentointi.  Huomaa, että kommentti aloitetaan kahdella asteriskilla (/**)
  3. Käytä työkalua valitsemalla Run ->Generate JavaDoc (ProjektinNimi)
    • Hetken kuluttua selaimen pitäisi käynnistyä ja näyttää dokumentointi.  Valitse listasta luokka, jonka metodin dokumentoit ja tarkastele lopputulosta.
    • Laitoksen koneilla selaimena aukeaa Konqueror, eikä Firefox - tämän ei kuitenkaan pitäisi haitata mitään.

Attribuuttien dokumentointi

Attribuuttien dokumentointi tehdään kuten metodienkin. 

/**
 * Kalibrointiarvo todennäköisyyden laskemiseen
 */
private int kalibrointi = 20;

 

Tarkempi dokumentointi

Laajennetaan vielä alussa esiteltyä esimerkkiä.  Metodille annetaan toinen parametri ja tämä dokumentoidaan omana @param-rivinä.  Lisäksi dokumentointiin lisätään "See Also" -kohta, jonka kautta HTML-dokumentissa liikkuminen laskukone-pakkauksen Laskenta-luokan laskeTn(int)-metodiin on helppoa.  Tämä ilmaistaan muodossa laskukone.Laskenta#laskeTn(int).  NetBeanssin control+space osaa täydentää projektin koodin mukaan tämän polun!

/**
 * Metodi kertoo mikä on onnistumistodennäköisyys syöteluvulla
 * ottaen huomioon olion konstruktorissa asetetun kalibrointiarvon
 *
 * @param   syote   Käyttäjän antama syöte
 * @param   kayttajanKorjaus    Käyttäjän antama korjausarvo
 * 
 * @see    laskukone.Laskenta#laskeTn(int)
 *
 * @return todennäköisyys kalibroituna
 */
public int onnistumistodennakoisyys(int syote, int kayttajanKorjaus) {
    int tn = super.laskeTn(syote) - this.kalibrointi - kayttajanKorjaus;
    return tn;
}

Tehtävä: Lisää @see määrittely ja kokeile koodin täydennystä.  Tämän jälkeen katso miltä generoitu dokumentti näyttää (generoi dokumentointi uudestaan)

Katso myös

Lisää muotoiluja löytyy allaolevista linkeistä:

Tulostettava sivuTulostettava sivu