MINISTERUL EDUCAŢIEI ȘI CERCETĂRII AL REPUBLICII MOLDOVA

IP CENTRUL DE EXCELENŢĂ ÎN INFORMATICĂ ŞI TEHNOLOGII INFORMAŢIONALE

CATEDRA DE INFORMATICĂ I

TUTORIAL
TEMATIC

LA UNITATEA DE CURS:
TEHNOLOGII AVANSATE DE PROGRAMARE

TEMA: Limbajul JavaDoc

Grupa: P-1841
Elev (ul/a):
Ciobanu Stanislav

Profesor:
Luncașu G.

Chişinău, 2021
 CUPRINS:

1. Noțiuni și elemente generale ale limbajului JavaDoc

2. Scopul utilizării limbajului JavaDoc

3. Tutorial scris cu imagini și pe pași explicat

4. Concluzie

5. Bibliografie

2
 Noțiuni și elemente generale ale
limbajului JavaDoc și scopul utilizării acestuia:

La documentarea unei aplicații, este necesar și suportul documentației

programului. Dacă documentația și codul sunt separate, atunci se creează, din neatenție,
complicații asociate cu necesitatea de a face modificări la secțiunile corespunzătoare ale
documentației însoțitoare atunci când se schimbă codul programului. De obicei,
majoritatea IDE-urilor (mediilor de dezvoltare) de aplicații Java existente oferă o soluție
pentru conectarea codului la documentație în timpul dezvoltării folosind un instrument
special, numit JavaDoc, despre care și o să meargă vorba în continuare.

Fig. 1 – Logotip-ul mascotă a instrumentului JavaDoc

JavaDoc este un instrument pentru generarea documentației standard în format

HTML, pe baza comentariilor dintr-un oarecare cod-sursă Java. El a fost dezvoltat de
compania Sun Microsystems. Deci, JavaDoc este un standard pentru documentarea
claselor Java. Acesta generează documentație API. Analizează declarațiile și
3
documentația într-un set de fișiere sursă care descriu clase, metode, constructori și
câmpuri. JavaDoc oferă, de asemenea, un API pentru crearea de docklet-uri și taglet-uri
care permit programatorului să analizeze structura unei aplicații Java. La moment cea
mai actuală versiune al JavaDoc este 1.50 .

Am menționat mai sus așa noțiune ca docklet… probabil v-ați pus întrebarea ce mai
sunt și aceste docklet-uri? Doclet-urile sunt niște programe care lucrează cu instrumentul
JavaDoc pentru a genera documentație pentru codul sursă scris în Java. Doclet-ele sunt
scrise în limbajul de programare Java și folosesc API-ul doclet pentru:

 Alegerea conținutului de inclus în document.

 Editarea prezentării conținutului.

 Crearea unui dosar care contine documentatia.

Aplicarea JavaDoc se face prin intermediul comentariilor documentației, care se

aplică pentru documentarea:

 claselor

 interfețelor

 câmpurilor (variabilelor)

 constructorilor

 metodelor

 pachetelor

A fost dezvoltată o sintaxă specială pentru formatarea documentației sub formă de

comentarii și un instrument pentru crearea documentației din comentarii. Acest
instrument, la procesarea fișierului cu codul sursă al programului, extrage documentația
marcată din comentarii și o asociază cu numele claselor, metodelor și câmpurilor
corespunzătoare. Astfel, cu efortul minim de a crea comentarii de cod, puteți obține o
documentație bună pentru program.

4
 Deci, ne amintim de faptul că când scriem comentarii la codurile Java, sunt
utilizate, în general, cele trei tipuri de comentarii:

// comentariu pe o linie

/ * comentariu pe
mai multe rânduri * /

/ ** comentariu de documentație * /

Folosind utilitarul JavaDoc inclus în cadrul JDK (Java Development Kit), comentariul
documentului poate fi extras și plasat într-un fișier HTML. Utilitarul JavaDoc vă permite
să inserați etichete HTML și să utilizați comenzi rapide (descriptori) pentru
documentație. Etichetele de antet НТМL nu sunt folosite pentru a nu încălca stilul
fișierului generat de utilitar. Se spune că descriptorii JavaDoc care încep cu semnul @
sunt autonomi și trebuie plasați la începutul liniei de comentariu (* principal este
ignorat). Descriptorii care încep cu o acoladă, cum ar fi {@code}, se numesc descriptori
inline și pot fi utilizați într-o descriere.

Înainte de a utiliza instrumentul JavaDoc, trebuie să realizăm documentarea unei

clase, metode sau variabile, incluzând comentarii JavaDoc, care încep cu combinația de
caractere /** urmată de corpul comentariilor; și se termină cu o combinație de caractere
* /. Aceste comentarii oferă informații despre clase, metode și constructori etc. Pentru a
crea un document API bun și ușor de înțeles pentru orice fișier Java, trebuie să scrieți
comentarii bune pentru fiecare clasă, metodă, constructor. În corpul comentariilor pot fi
5
introduși diverși descriptori. Fiecare descriptor care începe cu caracterul „@” trebuie să
apară primul pe linie. Mai mulți descriptori de același tip trebuie grupați împreună.
Descriptori în linie (începând cu o acoladă) pot fi plasați în interiorul oricărei descriere.
Comentariile JavaDoc sunt diferite de comentariile normale din cauza asteriscului
suplimentar de la începutul comentariului.

Următorii descriptori pot fi utilizați pentru a documenta o variabilă:

@see, @serial, @serialField, {@value}, @deprecated

Pentru clase și interfețe, pot fi folosiți descriptori:

@see, @author, @deprecated, @param, @version

Metodele pot fi documentate folosind descriptori:

@see, @return, @param, @deprecated, @throws, @serialData,
{@inheritDoc}, @exsertion

Iar, descriptorii care pot fi utilizați oriunde sunt:

{@link}, {@docRoot}, {@code}, {@literal}, @since, {@linkplain}

Puteți utiliza etichete HTML pentru a vă documenta codul. Când utilizați descriptori
de referință @see și @link, trebuie mai întâi să specificați numele clasei și după simbolul
„#” metoda sau câmpul acesteia. Haideți să analizăm un exemplu de utilizare a markup-
ului JavaDoc pentru a documenta o clasă (cu codul dat):
6
/**
* Clasa producției cu proprietățile <b>maker</b> și <b>price</b>.
* @autor Ciobanu Stanislav
* @version 1.2
*/
class Product
{
/** Câmpul producător */
private String maker;

/** Câmpul preț */

public double price;

/**
* Constructor - crearea unui obiect nou
* @see Product#Product(String, double)
*/
Product()
{
setMaker("");
price=0;
}

/**
* Constructor - crearea unui obiect nou cu anumite valori
* @param maker - producător
* @param price - preț
* @see Product#Product()
*/
Product(String maker,double price){
this.setMaker(maker);
this.price=price;
}

/**
* Funcția de primire a valorii câmpului {@link Product#maker}
* @return returnează denumirea producătorului
*/
public String getMaker() {
return maker;
}
7
 /**
* Procedura de determinare a producătorului {@link Product#maker}
* @param maker - producătorul
*/
public void setMaker(String maker) {
this.maker = maker;
}
}

Sau iată un exemplu de utilizare a markup-ului JavaDoc pentru a documenta o

metodă ce ține de o problemă de șah (cu codul dat):

/**
* <p>Verifică dacă mișcarea este validă.</p>
* <p>De exemplu, pentru a seta mutarea e2-e4, scrieți isValidMove
(5,2,5,4);</p>
* @param fromCol Verticala pe care se află figura (1=a, 8=h)
* @param fromRow Orizontala pe care se află figura (1...8)
* @param toCol Verticala pătratului către care se face mutarea (1=a,
8=h)
* @param toRow Orizontala pătratului către care se face mutarea (1=a,
8=h)
* @author Ciobanu Stanislav
* @version 1.0
* @return true, dacă mutarea este admisibilă, și false, dacă este
inadmisibilă
*/
boolean isValidMove(int fromCol, int fromRow, int toCol, int toRow) {
. . .
}

Apropo, chiar dacă scriem un număr mare de comentarii, acestea nu vor afecta
performanța programului Java, deoarece toate comentariile sunt eliminate în timpul
compilării. La fel, observați că JavaDoc este format din două părți (o descriere care este
urmată de etichete de bloc).

8
 Unele medii de dezvoltare integrate (IDE) generează automat fișierul JavaDoc, cum
ar fi NetBeans, IntelliJ IDEA, Eclipse etc. IDE-ul ajută de obicei programatorul evidențiind
documentația încorporată. Următoarele imagini sunt capturi de ecran ale ferestrelor pop-
up al mediului Eclipse IDE:

Generarea JavaDoc este simplă. Pentru a crea un JavaDoc, nu trebuie să compilăm

fișierul Java. Pentru a crea API-ul de documentație Java, trebuie să scrieți JavaDoc urmat
de numele fișierului sau al pachetului, astfel:
javadoc nume_fișier
javadoc nume_pachet

9
 După executarea cu succes a comenzii de mai sus, vor fi create un număr de fișiere
HTML, deschideți fișierul numit index pentru a vedea toate informațiile despre clase.

Pentru a genera JavaDoc în Eclipse, urmați pașii:

 Selectați opțiunea „Generare JavaDoc” din meniul Proiect și va apărea un

expert.

 Specificați locația fișierului JavaDoc de pe computer, implicit acesta va fi în

unitatea C.

 Selectați proiectul și apoi pachetele pentru care doriți să creați fișierul

JavaDoc.

 După aceasta, în partea dreaptă, selectați clasele pentru care doriți să

generați JavaDoc-ul, implicit toate clasele vor fi selectate.

 Apoi, puteți specifica și pentru ce clase va fi generat JavaDoc, selectând

vizibilitatea.

 Selectați locația de destinație în care va fi plasat JavaDoc-ul generat.

 Apoi faceți clic pe Next sau Finish.

 Dacă selectați Next în fereastra următoare, puteți selecta titlul

documentului și alte opțiuni de bază.

Mai jos o să examinăm încă un exemplu, numai că de data aceasta vă voi prezenta
nu doar implementarea comentariilor JavaDoc în fișierul Java, dar și generarea
documentației cu ajutorul comenzii javadoc. La fel, o să vedeți un screenshot cu pagina
html index din cadrul folder-ului documentației creat.

1
0
package exemplujavadoc;

import java.util.Scanner;

/**
*
* @author Ciobanu Stanislav
*/
public class Exemplu {
/**
* Acesta este un program pentru a adăuga 2 numere în Java.
* @param args
*/
public static void main(String[] args)
{
/**
* Aceasta este metoda main
* ea este foarte importantă pentru
* executarea oricărui program Java.
*/

int x, y;
Scanner sc = new Scanner(System.in);
/**
* Declararea a 2 variabile x și y.
* Cererea input-ului de la user
* folosind clasa Scanner.
*
*/

x = sc.nextInt();
y = sc.nextInt();
/**
* Salvarea rezultatului în variabila suma
* care este de tip integer.
*/
int suma = x + y;

/**
* Utilizăm fluxul standard de output
* pentru a afișa rezultatul.
1
1
 * @return null
*/
System.out.println("Suma este: " + suma);
}
}

Generarea JavaDoc pentru clasa (defapt tot pachetul) prezentată mai sus se
efectuează scriind comanda:
javadoc exemplujavadoc

1
2
 Concluzie

Lucrarea dată mi s-a părut destul de captivantă deoarece am aflat ceva cu

adevărat nou pentru mine, și anume fatpul că există instrumente speciale de creare
a documentației, până acum, din motiv că aveam cunoștințe limitate în acest sens,
credeam că documentația este scrisă manual de către programatori.

Vreau să concluzionez ceea ce am înțeles personal și pentru ce utilizăm

JavaDoc. Deci, utilizarea acestui instrument, constă în scrierea unor comentarii
speciale ce încep cu /**, în cadrul codului Java, înaintea elementelor (claselor,
metodelor, etc.). În cadrul acestor comentarii descriem aceste elemente folosind
descriptoare (ce încep cu @) și tag-uri HTML (precum <p> sau <b>, etc.).

Ulterior, utilitarul JavaDoc inclus în JDK și IDE, găsește aceste comentarii

și crează pe baza lor, documentația sub forma unor fișiere HTML, ierarhizate
frumos într-un folder.

Momentul-cheie este faptul că odată ce am făcut unele schimbări în codul

Java (inclusiv în comentarii), ele se aplică automat și în documentație, deoarece are
loc actualizarea fișierelor HTML. Acest lucru ne permite să nu scriem manual, de
fiecare dată, schimbările ce apar în cod, și în documentație.

Sunt încrezut că programatorii Java utilizează cu mare plăcere acest utilitar,

deoarece cunoaștem cu toții că elaborarea documentației ce însoțește codul, nu mai
este un indicator al profesionalismului, ci a devenit demult o cerință indispensabilă.

1
3
 Bibliografie

1. http://java-online.ru/java-javadoc.xhtml#top
2. https://www.geeksforgeeks.org/what-is-javadoc-tool-and-how-to-use-it/
3. https://ru.wikipedia.org/wiki/Javadoc
4. https://ru.wikipedia.org/wiki/Doclet

1
4