Documentați codul Java automat cu Javadoc

Dacă faci orice fel de programare, vei fi conștient de faptul că una dintre cele mai obositoare sarcini implicate este documentarea codului tău. Fie că vi se pare ușor enervant sau o acțiune cu care vă confruntați cu groază absolută, documentarea codului este esențială. Alții trebuie să înțeleagă cum funcționează codul dvs. și ați putea chiar să fiți unul dintre ei dacă îl citiți la o dată ulterioară!

Java oferă în mod convenabil o soluție încorporată la problemă: Javadoc.

Javadoc vă poate ajuta să vă documentați codul automat

Sper că te urmărești deja bune practici de codificare și includeți comentarii explicative în codul dvs. Deși acest tip de comentarii în cod este cu siguranță util, nu oferă cu adevărat nimic comparabil cu un manual.

Sigur, un alt programator poate să se uite prin codul tău și să citească despre clasele, metodele și funcțiile specifice care se află în fața lui. Cu toate acestea, este extrem de dificil să obțineți o imagine de ansamblu bună a întregului cod sau să găsiți funcții care ar putea fi utile atunci când nu știți că există. Javadoc își propune să rezolve această problemă.

Javadoc va genera automat un manual HTML detaliat și ușor de citit pentru întregul cod. Cel mai bine, o face folosind comentarii de cod pe care probabil le scrii deja.

Ce este exact Javadoc și cum funcționează?

Javadoc este un program de sine stătător care vine la pachet cu versiunile Oracle Java Development Kit (JDK). De fapt, nu îl puteți descărca separat. Când descărcați și instalați una dintre versiunile JDK ale Oracle, va instala și Javadoc.

Când îl rulați, Javadoc generează documentație HTML din comentarii formatate special din codul sursă Java. Acest proces creează o documentație mai utilă și mai lizibilă, încurajând totodată cele mai bune practici.

Pe scurt, Javadoc vă permite să vă scrieți codul și documentația în același timp. Vă simplifică fluxul de lucru și vă permite să utilizați mai eficient timpul.

Javadoc funcționează prin analizarea comentariilor formatate special în codul dvs. și conversia acestora în ieșire HTML. Singura modificare pe care trebuie să o faceți este să includeți anumite șiruri în comentarii. Acestea îi informează pe Javadoc ce doriți să includeți în documentația finală.

Comentariile Javadoc ar trebui să preceadă imediat o declarație de clasă, câmp, constructor sau metodă. Comentariul în sine ar trebui:

• Începeți cu cele trei personaje /**.
• Includeți un asterisc la începutul fiecărei linii noi.
• Încheiați cu cele două personaje */.

În comentarii, puteți include HTML în rezultatul final și include etichete care vor genera link-uri către părți relevante ale bazei de cod. Puteți chiar să utilizați lucruri precum etichetele de imagine HTML pentru a include imagini în documentația finală. Odată ce vă obișnuiți cu formatul și etichetele disponibile, scrieți astfel de comentarii este ușor.

Iată un exemplu pentru a ilustra comentarii Javadoc simple care descriu o funcție care primește o imagine de la o adresă URL și o imprimă pe ecran. Comentariul precede imediat funcția și descrie ceea ce face. Acest bloc de comentarii folosește și trei etichete specifice secțiunii: @param, @întoarcere, și @vedea.

/**
* Returnează un obiect Image care poate fi apoi pictat pe ecran.
* Argumentul url trebuie să specifice un absolut {@legătură URL}. Numele
* argumentul este un specificator care este relativ la argumentul url.
* 

* Această metodă revine întotdeauna imediat, indiferent dacă este sau nu
* imaginea există. Când acest applet-ul încearcă să deseneze imaginea
* pe ecran, datele vor fi încărcate. Elementele grafice primitive
* care desenează imaginea se va picta progresiv pe ecran.
*
* @param url o adresă URL absolută care oferă locația de bază a imaginii
* @param denumește locația imaginii, în raport cu argumentul url
* @întoarcere imaginea la adresa URL specificată
* @vedea Imagine
*/
public Imagine getImage(URL URL, nume șir){
încerca {
întoarcere getImage(nou URL(url, nume));
 } captură (MalformedURLException e) {
întoarcerenul;
 }
}

Când Javadoc procesează codul de mai sus, generează o pagină web similară cu următoarea:

Un browser redă ieșirea Javadoc în același mod în care afișează orice document HTML. Javadoc ignoră spațiul alb suplimentar și întreruperile de linie, cu excepția cazului în care utilizați etichete HTML pentru a crea spațiul respectiv.

Etichetele @ folosite la sfârșitul comentariului generează Parametrii, Se intoarce, și Vezi si secțiunile pe care le vedeți.

Ar trebui să urmați @param etichetă cu numele parametrului, un spațiu și o descriere a acestuia. În cazul de mai sus, există doi parametri: url și Nume. Observați că ambele apar sub același titlu Parametri în documentația de ieșire. Puteți enumera cât mai mulți parametri sunt necesari pentru funcția sau metoda pe care o descrieți.

The @întoarcere tag-ul documentează valoarea pe care funcția o returnează, dacă este deloc. Poate fi o simplă descriere cu un singur cuvânt sau mai multe propoziții, în funcție de circumstanțe.

The @vedea tag vă permite să etichetați alte funcții care sunt legate sau relevante. În acest caz, eticheta @see se referă la o altă funcție numită pur și simplu Imagine. Rețineți că referințele făcute cu această etichetă sunt link-uri pe care se poate face clic, permițând cititorului să sară la articolul referit în HTML-ul final.

Există mai multe etichete disponibile, cum ar fi @version, @author, @exception și altele. Atunci când sunt utilizate corect, etichetele ajută la legarea elementelor între ele și fac posibilă navigarea cu ușurință prin documentație.

Rularea Javadoc pe codul sursă

Invocați Javadoc pe linia de comandă. Îl puteți rula pe fișiere individuale, directoare întregi, pachete java sau pe o listă de fișiere individuale. În mod implicit, Javadoc va genera fișierele de documentație HTML în directorul în care introduceți comanda. Pentru a obține ajutor cu privire la comenzile specifice disponibile, pur și simplu introduceți:

javadoc --Ajutor

Pentru a vedea exact ce poate face Javadoc mai detaliat, consultați documentația oficială de la Oracol. Pentru a crea un set rapid de documentație pe un singur fișier sau director, puteți introduce javadoc pe linia de comandă, urmată de un nume de fișier sau de un wildcard.

javadoc ~/code/nume de fișier.java
javadoc ~/code/*.java

Mai sus este o listă a fișierelor și directoarelor create de Javadoc. După cum puteți vedea, sunt destul de multe dintre ele. Din acest motiv, ar trebui să vă asigurați că nu vă aflați în același director cu codul sursă atunci când rulați programul. Procedând astfel, ar putea crea o mizerie destul de mare.

Pentru a vizualiza documentele nou create, pur și simplu deschideți index.html fișier în browserul dvs. preferat. Veți primi o pagină ca următoarea:

Aceasta este documentația pentru o singură clasă Java scurtă pentru a demonstra rezultatul. Antetul arată numele clasei, precum și metodele incluse în ea. Derularea în jos dezvăluie definiții mai detaliate ale fiecărei metode de clasă.

După cum puteți vedea, pentru orice tip de proiect Java, în special pentru cele mari cu multe mii de linii de cod, acest tip de documentație este de neprețuit. Ar fi o provocare să înveți despre o bază de cod mare citind codul sursă. Paginile Javadoc fac acest proces mult mai rapid și mai ușor de urmărit.

Javadoc vă poate ajuta să vă mențineți codul Java și toată documentația relevantă organizate și ușor de utilizat. Indiferent dacă o faci pentru viitorul tău uituc sau pentru a ușura lucrurile pentru o echipă mare, Javadoc este un instrument puternic care poate schimba modul în care scrieți și interacționați cu codarea Java proiecte.

Cele mai bune 8 bloguri Java pentru programatori

Citiți în continuare