Cea mai mare problemă cu documentarea codului este de a susține această documentație. În cazul în care documentația și codul sunt separate, există dificultăți asociate cu necesitatea modificării secțiunilor relevante din documentația însoțitoare ori de câte ori se modifică codul. Mediul de dezvoltare oferă o soluție - de a lega codul cu documentația, punând totul într-un fișier.
Utilitarul javadoc vă permite să inserați etichete HTML și să utilizați comenzi rapide speciale (descriptori) pentru documentare. Etichetele antet NTML nu sunt folosite pentru a nu încălca stilul fișierului generat de utilitate.
Pentru a documenta o variabilă, puteți utiliza următoarele descriptori:
Pentru clase și interfețe, puteți utiliza descriptori:
Metodele pot fi documentate folosind descriptori:
După combinația inițială de caractere / **, este localizat textul care este descrierea principală a clasei, variabilei sau metodei. Apoi puteți introduce diferite descriptori. Fiecare descriptor @ trebuie să fie primul din șir. Mai multe descriptori de același tip trebuie să fie grupate împreună. Descriptorii încorporați (începând cu o bretele) pot fi plasați în orice descriere.
Utilitarul javadoc acceptă fișierul sursă al programului ca intrare. Generează mai multe fișiere HTML care conțin documentația pentru acest program. Informațiile despre fiecare clasă vor fi conținute într-un fișier HTML separat. În plus, se creează un arbore index și o ierarhie. Alte fișiere HTML pot fi, de asemenea, generate.
În mediul Eclipse, puteți genera documentație utilizând comanda de meniu Project / Generate Javadoc.
Descriptori pentru javadoc
@author Descriere
- opțiunea de autorizare pentru a include câmpul în documentația HTML.
@ descriere descrisă
Specifică faptul că clasa, interfața sau memoria clasei este depreciată. Se recomandă includerea descriptorilor sau informarea programatorului despre alternativele disponibile. Poate fi folosit pentru a documenta variabile, metode și clase.
Specifică calea către directorul rădăcină al documentației curente.
@excepție exclude_name explicație
Descrie excepția pentru această metodă. Aici, exclude_name specifică numele complet al excepției, iar explicația reprezintă un șir care descrie cazurile în care poate apărea această excepție. Poate fi folosit numai pentru a documenta metode.
Încorporează un link către informații suplimentare. Când este afișat, textul (dacă este prezent) este folosit ca nume de link.
@param nume_parametru
Documentați un parametru pentru metoda sau tipul de parametru pentru clasă sau interfață. Poate fi folosit doar pentru a documenta o metodă, un constructor, o clasă generică sau o interfață.
@ explicație retur
Descrie valoarea returnată a metodei.
@ a se vedea pachetul.class # text element
Oferă un link către informații suplimentare.
@ descriere seria
@serialData Descriere
Documentați datele scrise folosind metodele writeObject și writeExternal.
Descrierea tipului de nume @serialField
de la lansare
Indică faptul că elementul de clasă sau de clasă a fost introdus pentru prima dată într-o versiune specială. Aici, versiunea reprezintă linia în care este specificată versiunea sau versiunea, din care această caracteristică a devenit disponibilă.
@ numește scutiți
Are același scop ca și descriptorul @exception.
Afișează valoarea următoarei constante, care ar trebui să fie câmpul static.
Afișează valoarea unui câmp static specific.
@ informații despre versiune
Reprezintă informații despre versiune (de obicei un număr). Când rulați utilitarul javadoc, trebuie să specificați opțiunea -versiune pentru a permite acestui descriptor să includă documentația în NTML.
Articole similare
Trimiteți-le prietenilor: