Limbajul java suport trei tipuri de comentarii
- /* comentariu */
Compilatorul ignora tot ce este intre /* si */ - // comentariu
Compilatorul ignora tot ce se afla dupa „//” pana la sfarsitul liniei - /** documentatie */
Acesta este un comentariu pentru documentatie si in general se numeste „doc comment”. Unealta JDK javadoc utilizeaza comentariile de acest tip atunci cand pregateste generarea automata a documentatiei.
Acest tuorial este special pentru a explica ultimul tip de comentarii. Vom vedea in randurile urmatoare cum putem genera o documentatie folositoare pentru codul nostru Java.
Ce este Javadoc?
Javadoc este o unealta ce vine impreuna cu JDK si este folosita pentru a genera documentatia codului Java intr-un format HTML, ceea ce necesita un format predefinit al comentariilor.
Exemplu:
/**
* Programul Tutorial este o aplicatie simpla
* ce va scrie "Hello World!" pe ecran.
*
* @author Tutoriale-Pe.NET
* @version 1.0
* @since 2017-01-31
*/
public class Tutorial{
public static void main(String[] args) {
System.out.println("Hello World!");
}
}
De asemenea, putem include tag-uri specifice codului HTML in interiorul acestui tip de comentariu. De exemplu urmatorul cod foloseste tag-urile <h1>…</h1> pentru heading si <p> pentru a creea un paragraf cu spatiu.
Exemplu:
/**
* <h1>Tutoriale-Pe.NET</h1>
* Programul Tutorial este o aplicatie simpla
* ce va scrie "Hello World!" pe ecran.
* <p>
* Folosind tipul potrivit de comentarii in programul tau
* il face sa para mult mai prietenos si este vazut
* ca un cod de calitate inalta.
*
*
* @author Tutoriale-Pe.NET
* @version 1.0
* @since 2017-01-31
*/
public class Tutorial{
public static void main(String[] args) {
System.out.println("Hello World!");
}
}
Tag-urile Javadoc
Unealta javadoc tool recunoaste urmatoarele tipuri de comentarii:
| Tag | Descriere | Sintaxa |
|---|---|---|
| @author | Adauga autorul clasei | @author Numele Autorului |
| {@code} | Afiseaza textul in acelasi font al codului, fara a-l interpreta ca si limbaj HTML sau ca si tag-uri Javadoc | {@code text} |
| {@docRoot} | Reprezinta calea catre folderul documentatiei din orice pagina generata. | {@docRoot} |
| @deprecated | Adauga un comentariu care sa indice faptul ca acea clasa nu ar mai trebuii sa fie folosita | @deprecated text |
| @exception | Adauga subheading-ul „Throw”s pentru documentatia generata cu numele clasei cat si o descriere. | @exception numele-clasei descriere |
| {@link} | Adauga o legatura catre un anumit pachet, clasa, sau membru dintr-o clasa urmat de o simpla descriere. | {@link pachet.clasa#membru descriere} |
| {@linkplain} | La fel ca si @link, doar ca descrierea este intr-un font normal, nu in fontul specific codului | {@linkplain pachet.clasa#membru descriere} |
| @param | Adauga descrierea unui parametru. Trebuie mai intai sa mentionezi numele parametrului iar mai apoi descrierea acestuia. | @param parameter-name description |
| @return | Adauga o sectiune „Returns” impreuna cu o descriere | @return descriere |
| @see | Adauga heading-ul „See Also” – poti sa pui un link, sau mai multe puncte de referinta. | @see referinta |
| @since | Adauga subheading-ul „Since” alaturi de descrierea mentionata | @since descriere |
| @throws | Tagurile @throws si @exception sunt sinonime (= fac acelasi lucru)/ | @throws numele-clasei descriere |
| @version | Adauga un subheading „Version” in care este specificat un text catre documentatia deja generata atunci cand folosim optiunea -version. | @version text |
*Acestea NU sunt toate tag-urile Javadoc, sunt doar cateva dintre cele mai utilizate!
Exemplu
Urmatorul program foloseste cateva dintre cele mai importante tag-uri disponibile pentru documentatie. Puteti folosii si alte tag-uri, in functie de necesitatile voastre.
Documentatia despre clasa AdunaNumere va fi exportata intr-un fisier HTML denumit AdunaNumere.html dar in acelasi timp un fisier master se va creea cu numele index.html
import java.io.*;
/**
* <h1>Tutoriale-Pe.NET</h1>
* Programul Tutorial este o aplicatie simpla
* ce va scrie "Hello World!" pe ecran.
* <p>
* Folosind tipul potrivit de comentarii in programul tau
* il face sa para mult mai prietenos si este vazut
* ca un cod de calitate inalta.
*
*
* @author Tutoriale-Pe.NET
* @version 1.0
* @since 2017-01-31
*/
public class AdunaNumere{
/**
* Aceasta functie este folosita pentru a aduna
* doua numere intregi - este cea mai simpla
* functie pe care o puteam creea ca sa ne folosim
* de cateva tag-uri Javadoc.
* @param numarulA Acesta este primul parametru din functia aduna
* @param numarulB Aceste este al doilea paramestru din functia aduna
* @return int Aceasta functie returneaza suma celor doi parametrii.
*/
public int aduna(int numarulA, int numarulB) {
return numarulA + numarulB;
}
/**
* Aceasta este functia main in care folosim functia aduna
* @param args Nefolosite.
* @exception IOException atunci cand avem erori la prelucrarea datelor.
* @see IOException
*/
public static void main(String args[]) throws IOException {
AdunaNumere obj = new AdunaNumere();
int sum = obj.aduna(80, 19);
System.out.println("Suma numerelor 80 si 19 este: " + sum);
}
}
Acum intram in Command Prompt (CMD) si scriem javadoc AdunaNumere.java, si o sa vedem urmatorul ecran:
Trebuie sa navigam pana la fisierul AdunaNumere.java si executam comanda „javadoc”
Pentru cei care vor sa vada rezultatul final, pot sa dea click aici: AdunaNumere.
Daca aveti nelamuriri sau intrebari, va asteptam cu drag pe Facebook pentru a clarifica orice problema.
