**Javadoc** on dokumentaation luoja. Javadocin on alun perin kehittänyt Sun Microsystems Java-ohjelmointikielle, jonka nykyään omistaa Oracle Corporation. Javadoc luo API-dokumentaation HTML-muotoon Java-lähdekoodin perusteella. HTML-muotoa käytetään, jotta pystytään käyttämään linkkejä dokumentaatiossa.

Javadoc ei vaikuta ohjelman suorituskykyyn, koska kaikki kommentit poistetaan ohjelmakoodia käännettäessä. Kommentointi ja dokumentaatio parantaa ohjelmakoodin ylläpidettävyyttä.

Tekninen arkkitehtuuri
----------------------

### Javadoc-kommentin rakenne

Javadoc-kommentti eroaa tavallisesta monirivisestä koodissa olevasta kommentista niin, että siinä on yksi tähtimerkki enemmän lähtömerkissä "/\*\*….\*/". Ensimmäinen kappale on dokumentoitavan metodin kuvaus ja muut kappaleet ovat antavat tarkempaa tietoa metodista. Kappaleita voi merkitä niiden sisällön perusteella. Keskeisimpiä ovat:

* "@param" metodin parametrit
* "@return" mitä metodi palauttaa
* "@throws" mitä mahdollisia virheitä metodi heittää
* "@see" hyvä tietää

### Javadoc-merkintöjä

Alla olevassa taulukossa on osa saatavilla olevista Javadoc-merkinnöistä:

| Merkintä & parametri | Käyttö |
| --- | --- |
| **@author** Matti Meikäläinen | Kertoo tekijän nimen. |
| **@exception** luokka kuvaus
**@throws** luokka kuvaus | Kuvaus mahdollisista poikkeuksista, mitä metodi voi palauttaa. |
| **@deprecated** kuvaus | Kuvaus ei käytössä olevasta metodista. |
| **@param** nimi kuvaus | Kuvaus metodin parametrista. |
| **@return** kuvaus | Kuvaus metodin palauttamasta arvosta. |
| **@see** viittaus | Linkki toiseen kohtaan dokumentaatiossa. Luo "See Also" -kohdan dokumentaation loppuun. |
| **{@link** viittaus} | Linkki toiseen kohtaan dokumentaatiossa. Luo linkin määriteltyyn kohtaan dokumentaatiossa. |
| **@version** versio | Kertoo tiedoston tai julkaisun nykyisen version. |
| **@since** versio | Kertoo missä versiossa kyseinen ominaisuus luotiin. |

Hyvät tavat
-----------

### Metodin dokumentointi

Alla oleva esimerkin ensimmäisessä kohdassa (1) kuvaillaan lyhyesti metodin toiminta. Toisessa kohdassa (2) voidaan kuvailla tarkemmin metodin toimintaa useammalla lauseella. Kolmannessa kohdassa (3) käytetään merkintöjä kuvailemaan metodin saamia parametreja. Kommentissa on mahdollista käyttää HTML-muotoiluja, kuten rivinvaihtoa <p>.

```
/\*\*
 \* Lyhyt yhden rivin kuvaus. (1)
 \* <p>
 \* Pidempi kuvaus, jota on mahdollista jakaa useampiin kappaleisiin. (2)
 \* <p>
 \* Kuvaus viedään HTML koodiin, joten HTML muotoilut ovat mahdollisia,
 \* kuten yllä oleva rivinvaihto.
 \*
 \* @param Rivin alkumerkintä tarkoittaa parametriä ja tähän ne voi kuvata. (3)
 \* @return Rivin alkumerkintä tarkoittaa metodin palautusta ja arvoja voi kuvailla tähän.
 \*/
public int metodinNimi (...) {
 // Metodin ohjelmakoodi
}

```

### Muuttujien dokumentointi

Muuttujat dokumentoidaan samalla tyylillä kuin metodit, mutta kohta (3) jätetään pois. Tässä muuttuja sisältää vain lyhyen kuvauksen:

```
/\*\*
 \* Muuttujan kuvaus tähän.
 \*/
 private int luku = 0;

```
Useamman muuttujan määrittely yhden Javadoc-kommentin alle ei ole suositeltua. Tämä siitä syystä, että Javadoc lukee jokaisen muuttujan erikseen ja sijoittaa ne luodulle HTML-sivulle erilleen toisistaan dokumentoinnin pysyessä samana. 

```
/\*\*
 \* Pisteen vaaka- ja pystyetäisyys (x,y).
 \*/
 public int x, y; // VÄLTÄ TÄTÄ

```
Ylläolevan koodin pohjalta lopputulos näyttäisi seuraavalta:

```
 public int x
Pisteen vaaka- ja pystyetäisyys (x,y).

 public int y
Pisteen vaaka- ja pystyetäisyys (x,y).

```
On suositeltua määritellä ja dokumentoida muuttujat erikseen selkeyden vuoksi:

```
/\*\*
 \* Pisteen vaakaetäisyys.
 \*/
 public int x;
 
 /\*\*
 \* Pisteen pystyetäisyys.
 \*/
 public int y;

```

### Esimerkki

Esimerkki Javadoc-dokumentaatiosta:

```
/\*\*
 \* Vahvistaa shakkiliikkeen.
 \* 
 \* <p>Käytä {@link #teeSiirto(int alkuSarake, int alkuRivi, int loppuSarake, int loppuRivi)} shakkinappulan siirtämiseen.
 \* 
 \* @param alkuSarake sarake josta nappula siirtyy
 \* @param alkuRivi rivi josta nappula siirtyy
 \* @param loppuSarake sarake johon nappula siirtyy
 \* @param loppuRivi rivi johon nappula siirtyy
 \* @return tosi, jos siirto on laillinen, muulloin epätosi
 \* @since 1.0
 \*/
 boolean tarkistaSiirto(int alkuSarake, int alkuRivi, int loppuSarake, int loppuRivi) {
 // ...koodi
 }
 
 /\*\*
 \* Siirtää shakkinappulaa.
 \* 
 \* @see java.math.RoundingMode
 \*/
 void teeSiirto(int alkuSarake, int alkuRivi, int loppuSarake, int loppuRivi) {
 // ...koodi
 }

```

Lähteet
-------

1. ↑  javadoc-The Java API Documentation Generator. Section "Javadoc Tags" *docs.oracle.com*. Viitattu 3.4.2023.
2. ↑  javadoc *docs.oracle.com*. Viitattu 31.3.2023.
3. ↑  "Java Platform, Standard Edition Tools Reference for Oracle JDK on Solaris, Linux, and OS X, Release 8. Section "Multiple-Field Declarations". *docs.oracle.com*. Viitattu 3.4.2023.