fbpx

Java – Comentariile pentru documentatie (Javadoc)

0

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:

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:

javadoc AdunaNumere.java
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.

Comentarii
Se incarca comentariile...

This website uses cookies to improve your experience. We'll assume you're ok with this, but you can opt-out if you wish. Accept Read More