Java – Comentariile pentru documentatie (Javadoc)

Limbajul java suport trei tipuri de comentarii

1. /* comentariu */
   Compilatorul ignora tot ce este intre /* si */
2. // comentariu
   Compilatorul ignora tot ce se afla dupa “//” pana la sfarsitul liniei
3. /** 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:

*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.