C ++: Crearea documentatiei cu Doxygen - dummies

Majoritatea programatorilor nu doresc să creeze documente chiar mai mult decât urăsc să-și comenteze propriul cod. Introduceți Doxygen, care permite programatorilor să încorporeze etichete în comentariile care pot fi extrase ulterior pentru a crea documentația.

Instalarea Doxygen

Doxygen nu vine cu Cod:: Blocuri (cel puțin nu din această scriere). Va trebui să descărcați versiunea corectă a Doxygen pentru aplicația dvs. (De asemenea, există un link către site-ul Doxygen din site-ul Cod:: Blochează.) După ce vă conectați la site-ul Doxygenorg, puteți naviga la pagina de descărcare și găsiți versiunea Doxygen pentru sistemul dvs. de operare, după cum se arată aici:

Descărcați și instalați versiunea potrivită pentru sistemul dvs. de operare. Puteți accepta setările implicite, însă nu uitați unde expertul de instalare pune fișierul executabil Doxygen.

Acum începe Cod:: Blocuri. Selectați DoxyBlocks → Deschidere Preferințe. De acolo, selectați fila General și setați Calea către Doxygen. (Aceasta este calea pe care ați observat-o în paragraful anterior.) Calea implicită pentru Windows este C: Program Filesdoxygenbindoxygen. executabil. Faceți același lucru pentru calea către Doxywizard. Aici implicit pentru Windows este C: Program Filesdoxygenbindoxywizard. exe . Puteți lăsa celelalte unelte goale, deoarece acestea nu sunt necesare atunci când se generează documentația în format HTML.

Adăugarea de comentarii referitoare la documentație

Doxygen utilizează comentarii speciale pentru a marca cuvintele cheie care ajută instrumentul să creeze documentație. Cu destulă confuzie, Doxygen acceptă mai multe standarde diferite, dar implicit este cel care arată cel mai mult ca JavaDoc, comentariul / ** , ceea ce este bine. (Puteți modifica stilul de comentariu la unul dintre celelalte prin selectarea DoxyBlocks → Deschidere Preferințe și apoi selectarea fișei Stilul Comentariu.)

Pentru a vedea cum funcționează aceasta, plasați cursorul la începutul unei funcții și selectați DoxyBlocks → Blocare comentariu (sau apăsați Ctrl + Alt + B). Un comentariu cum ar fi următorul exemplu apare (următoarele exemple folosesc programul Budget5 care apare în materialul descărcabil la www. Dummies.com / extras / cplusplus):

/ ** brief * * param accList list & * return void * * / void getAccounts (list & accList) {

Cod:: Blocurile inserează un comentariu bloc de Doxygen începând cu / **. Doxygen știe că acest comentariu aparține definiției funcției care urmează imediat. Cuvintele cheie Doxygen încep cu un (backslash). Cuvântul scurt prezintă o scurtă descriere a funcției. Descrierea scurtă se poate extinde pe mai multe linii.Aceasta ar trebui să fie o scurtă descriere a funcției care apare în afișajele tabulare.

Programatorul poate urma acest lucru printr-o descriere mai detaliată marcată cu cuvântul cheie detalii . Această descriere detaliată oferă o descriere mai detaliată a funcției.

Multe dintre cuvintele cheie Doxygen sunt opționale. În special, cuvântul cheie detalii este asumat dacă începeți un paragraf separat de descrierea scurtă cu doar o linie necompletată.

Dincolo de aceasta este o linie separată marcată cu cuvântul cheie param pentru a descrie fiecare argument al funcției. În cele din urmă, cuvântul cheie return descrie valoarea returnată de funcție.

Când se completează, comentariul Doxygen pentru getAccounts () poate să apară după cum urmează:

/ ** brief getAccounts - conturi de intrare de la tastatură * detalii Această funcție citește intrarea de la tastatură. * Pentru fiecare intrare S sau C, funcția creează un nou obiect * Savings sau Checking și îl adaugă în lista de conturi *. Un X termină intrarea. Orice altă intrare * este presupusă a fi un depozit (numere mai mari de * 0) sau o retragere (numere mai mici de 0). * * param accList list & lista obiectelor create de cont * getAccounts () * return void * / void getAccounts (list & accList) {

De asemenea, puteți adăuga un comentariu Doxygen pe aceeași linie. Acest lucru este cel mai adesea folosit atunci când comentați membrii de date. Plasați cursorul la capătul liniei și selectați DoxyBlocks → Line Comment sau apăsați Ctrl + Alt + L. Completați acum o descriere a membrului de date. Rezultatul apare ca în exemplul următor, de asemenea, luat din Buget5:

bilanț dublu; / ** 

Generarea documentației Doxygen
Doxygen poate genera documentație în mai multe formate diferite, deși unele (cum ar fi HTML compilate) necesită descărcări ulterioare. Formatul HTML este deosebit de convenabil, deoarece nu necesită altceva decât un browser pentru vizualizare.
Implicit este HTML, dar dacă doriți să modificați formatul, selectați DoxyBlocks → Open Preferences, apoi selectați fila Doxyfile Defaults 2. În această fereastră puteți selecta toate formatele diferite pe care doriți să le generați.
Înainte de a extrage prima dată documentația, probabil că doriți să selectați câteva alte opțiuni. Selectați DoxyBlocks → Deschidere Preferințe, apoi selectați fila Doxyfile Defaults. Asigurați-vă că este bifată caseta Extras toate. Apoi selectați fila Doxyfile Defaults 2 și bifați caseta de validare Class_Diagrams. Acum, selectați fila General și bifați caseta Executare HTML după compilare. Faceți clic pe OK și ați terminat. (Nu veți mai avea nevoie să faceți acest lucru din nou, deoarece opțiunile sunt salvate într-un fișier numit doxyfile.)
Selectați DoxyBlocks → Extract Documentation pentru a genera și vizualiza documentația. După un interval destul de scurt, Doxygen deschide browser-ul dvs. preferat cu o documentație ca cea prezentată în figura următoare.
Doxygen nu este foarte prietenos atunci când vine vorba de erori de intrare. Uneori Doxygen se oprește să genereze documentație la un moment dat din sursa dvs. fără un motiv evident.Verificați doxygenul. fișierul jurnal conținut în același director ca fișierul doxy pentru eventualele erori care s-au produs în timpul extragerii.
Imaginea următoare arată browserul de proiect din fereastra din stânga care permite utilizatorului să navigheze în documentația proiectului. În dreapta, funcția getAccounts () a fost selectată pentru a obține o descriere mai detaliată. Descrierea scurtă apare pe prima linie, urmată de descrierea detaliată, parametrii și valoarea returnată:

Documentația de clasă este la fel de amănunțită, după cum arată următorul fragment de cod.
/ ** clasa Cont * scurtează un cont bancar abstract. * detalii Această clasă abstractă include * propertiescommon pentru ambele tipuri de cont: * Verificare și economii. Cu toate acestea, este lipsit de retragerea conceptului * (*), care este diferit * între contul de două * / clasa {

Documentația pentru Contul este afișată aici:

Observați descrierea care apare sub clasa cont . Aceasta este scurta descriere. Dacă faceți clic pe Mai multe, veți ajunge la descrierea detaliată. De asemenea, observați reprezentarea grafică a relației de moștenire dintre Account , clasele părinților și clasele pentru copii.