Kako naredim v Javi to in to

Dodajanje komentarjev v izvorno kodo z javadoc

Predstavitev

Ena lepših stvari pri Javi je javadoc. Orodje javadoc vam omogoča, da komentarje pišete poleg vaše kode, znotraj vaših ".java" izvornih datotek. Ko ste zadovoljni s svojo kodo in komentarji, enostavno poženete ukaz javadoc, ki vam avtomatično ustvari dokumentacijo v HTML slogu.

Shranjevanje komentarjev poleg kode poenostavi hkratno vzdrževanje obojega. Ko spremenite kodo, spremenite še komentarje ter še enkrat poženete javadoc. Zelo enostavno, zelo čisto.

Delujoč primer

Koda, prikazana v izpisu 1, lepo prikazuje, kako izgledajo Javadoc komentarji. Za trenutek pozabite, kaj ta Java koda počne (tako ali tako ne počne veliko), in se osredotočite na komentarje.

Prva stvar, ki jo je potrebno opaziti, je, da se javadoc komentarji začnejo z znakom /** in končajo z znakom */. To je nekoliko drugače od komentarjev v standardnem C ali C++ slogu, ki ste jih najbrž vajeni.

/**
* Porsche.java - a simple class for demonstrating the use of javadoc comments.
* @author Robert Newey
* @version 1.0
* @see Automobile
*/

public class Porsche extends Automobile {

protected String color;

   /**
    * Retrieve the value of color.
    * @return A String data type.
    */
   public String getColor() {
      return color;
   }

   /**
    * Set the value of color.
    * @param newColor A variable of type String.
    */
   public void setColor(String newColor) {
      color = newColor;
   }
}

Izpis 1: Ta vzorčna datoteka prikazuje, kako lahko na enostaven način v vašo Java kodo vključite komentarje v javadoc slogu.

Kot lahko vidite iz izpisa, vam javadoc omogoča tudi definiranje določenih oznak znotraj vaših javadoc komentarjev. Uporaba teh oznak povzroči, da javadoc v vašem imenu ustvari dodatno (in boljšo) dokumentacijo. Tabela 1 na kratko opisuje namen javadoc oznak, ki so bile uporabljene v vzorčni kodi iz izpisa 1.

`@author`	Ta oznaka vam dovoljuje vstavitev imena avtorja kode v dokumentacijo.
`@parameter`	To oznako uporabite za definiranje parametrov, ki se posredujejo metodi.
`@return`	Ta oznaka definira vrednosti, ki jih metode vračajo.
`@see`	Ta oznaka ustvari "Glej tudi:" izpis. Z uporabo le-te boste običajno podajali povezave do sorodnih razredov.
`@version`	Ta oznaka vam omogoča definiranje verzije Java kode, ki jo razvijate. Koda, prikazana v izpisu 1, pripada na primer verziji 1.0.

Tabela 1: Ta tabela podaja kratek opis najpogosteje uporabljanih javadoc oznak.

Kako deluje

V zvezi z javadoc morate paziti le na nekaj pravil. Pri kreiranju javadoc dokumentacije za vašo kodo jih imejte vedno v mislih:

Javadoc komentarji imajo pomen le, če se pojavijo pred javnim razredom, ali pred javnimi ali zaščitenimi spremenljivkami ali metodami.

Prva vrstica javadoc komentarja je vrstica s povzetkom. Ta opis boste videli na vrhu HTML datoteke za razred (to je Prosche.html) in pa tudi v datoteki AllNames.html.

Upoštevajte tudi, da ni potrebno vsake vrstice komentarjev začeti z zvezdico, kot smo to storili v izpisu 1. To je le dogovor med mnogimi programerji, ni pa standard. Če vam ta dogovor ni všeč, komentarje zgolj začnite z znaki /** in končajte z znakoma */.
Ko ste kodo enkrat napisali, samo še poženite ukaz javadoc na vaši ".java" datoteki:

javadoc Porsche.java

Ko boste to storili, bo javadoc generiral doumentacijo v HTML formatu za vse vaše javne razrede ter vaše javne in zaščitene metode in spremenljivke. Na podlagi datotek, ki jih podate, in dokumentacije znotraj teh datotek javadoc ustvari štiri tipe HTML datotek, kot so prikazani v tabeli 2:

`packages.html`	Izpis vseh paketov, za katere generirate dokumentacijo, in vseh razredov, ki jih ti paketi vsebujejo. V tako kratkem primeru, kot je naš, ta datoteka ne bo vsebovala nikakršnih zares uporabnih informacij.
`AllNames.html`	Ta datoteka vsebuje abecedno kazalo vseh spremenljivk in metod, ki ste jih definirali.
`tree.html`	Izpis vseh razredov, za katere ste generirali dokumentacijo, skupaj z njihovim položajem v hierarhiji razredov.
`Porsche.html`	Za vsak definirani razred bo ena datoteka takšnega tipa. Ta datoteka vsebuje dejansko dokumentacijo za razred.

Tabela 2: Ta tabela podaja kratke opise datotek, ki se ustvarijo po klicu ukaza javadoc na vaših Java izvornih datotekah.

Izpis javadoc dokumentacije

Naj bo dovolj o tem, kako deluje. Resnično delovanje javadoc se najboljše prikaže s samim izpisom, ki ga generira. Kliknite na povezave spodaj in si oglejte različne izpise dokumentacije, ki jih je javadoc kreiral za enostavno datoteko Porsche.java, ki je prikazana v izpisu 1.

Mislim, da se boste po ogledu dokumentacije, ki jo je kreiral javadoc, strinjali z mano, da je mnogo lažje prepustiti težko delo javadoc! Pomislite na prednosti:

Dokumentacija je poleg kode. Ob spreminjanju kode z lahkoto spremenite tudi dokumentacijo.
Za vas ustvari štiri različne tipe dokumentacijskih datotek. Te pri objektno usmerjenem programiranju zares potrebujete.
Vsi štirje različni tipi datotek so med sabo povezani, tako da vas klik na povezavo v eni datoteki popelje direktno v drugo datoteko. Ali si lahko predstavljate, da bi to delali ročno?

Naložite si vzorčno izvorno kodo

Če javadoc še ne uporabljate, vam predlagam, da poskusite. Začnete lahko kar z vzorčno kodo v izpisu 1. Če si želite naložiti izvorno kodo Porsche.java, ki je prikazana v izpisu 1, kliknite sem. Ko bo datoteka enkrat prikazana v vašem brskalniku, lahko izberete opcijo Datoteka | Shrani kot... in tako shranite kodo v vaš lokalni datotečni sistem.

avtor: Damir Arh
december, 1998