C ++: Skapa dokumentation med Doxygen-dummies

De flesta programmerare hatar att skapa dokumentation ännu mer än de hatar att kommentera sin egen kod. Ange Doxygen, som gör att programmerare kan bädda in taggar i kommentarerna som senare kan extraheras för att skapa dokumentationen.

Installera Doxygen

Doxygen kommer inte med kod:: Block (åtminstone inte enligt detta skrivande). Du måste ladda ner rätt version av Doxygen för din ansökan. (Det finns också en länk till Doxygen-webbplatsen från webbplatsen Kod:: Blocks.) När du har länkat till Doxygenorgs webbplats kan du navigera till nedladdningsidan och hitta versionen av Doxygen för operativsystemet, som visas här:

Hämta och installera den version som passar ditt operativsystem. Du kan acceptera standardinställningarna, men kom ihåg var installationsguiden lägger ut den körbara filen Doxygen.

Börja nu Kod:: Block. Välj DoxyBlocks → Öppna inställningar. Därifrån väljer du fliken Allmänt och anger sökvägen till Doxygen. (Det här är sökvägen du noterade i föregående stycke.) Standardvägen för Windows är C: Program Filesdoxygenbindoxygen. exe. Gör samma för vägen till Doxywizard. Här är standard för Windows C: Program Filesdoxygenbindoxywizard. exe . Du kan lämna de andra verktygen tomma eftersom de inte behövs när du genererar dokumentation i HTML-format.

Lägga till dokumentations kommentarer

Doxygen använder speciella kommentarer för att flagga nyckelord som hjälper verktyget att skapa dokumentation. Förvirrande nog accepterar Doxygen flera olika standarder, men standarden är den som ser mest ut som JavaDoc, den / ** kommentaren, vilket är bra. (Du kan ändra kommentarstilen till en av de andra genom att välja DoxyBlocks → Öppna inställningar och sedan välja fliken Kommentarstil.)

För att se hur detta fungerar, placera markören i början av en funktion och välj DoxyBlocks → Block Comment (eller tryck Ctrl + Alt + B). En kommentar som följande visas (följande exempel använder programmet Budget5 som visas i det nedladdningsbara materialet på www. Dummies. Com / extras / cplusplus):

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

Kod:: Block infogar en Doxygen block kommentar som börjar med / **. Doxygen vet att den här kommentaren hör till den funktionsdefinition som direkt följer. Doxygen sökord börjar med en (backslash). Sökordet kort flaggar den korta beskrivningen av funktionen. Den korta beskrivningen kan sträcka sig över mer än en rad.Detta bör vara en kort beskrivning av funktionen som visas i tabellformat.

Programmeraren kan följa detta med en mer noggrann beskrivning som flaggats med detaljerna nyckelord. Denna detaljerade beskrivning ger en mer noggrann beskrivning av vad funktionen gör.

Många av Doxygen-nyckelorden är frivilliga. I synnerhet antas sökordet detaljer om du startar en paragraf som är skild från beskrivningen kortfattad med ingenting mer än en tom linje.

Utöver det är en separat linje flaggad med sökordet param för att beskriva varje argument till funktionen. Slutligen beskriver sökordet retur det värde som returneras av funktionen.

När du fyller i kan Doxygen-kommentaren för getAccounts () visas som följer:

/ ** korta getAccounts - matar in konton från tangentbordet * detaljer Denna funktion läser inmatning från tangentbordet. * För varje S eller C som angetts skapar funktionen ett nytt * Spara eller Kontokontrollobjekt och lägger till det i * Kontolistan. En X avslutar posten. En annan * inmatning antas vara en insättning (antal större än * 0) eller ett uttag (antal mindre än 0). * * param accList lista och lista över konto * objekt skapade av getAccounts () * return void * / void getAccounts (list & accList) {

Du kan också lägga till en Doxygen-kommentar på samma rad. Detta används oftast när kommenterar data medlemmar. Placera markören i slutet av raden och välj antingen DoxyBlocks → Line Kommentar eller tryck Ctrl + Alt + L. Fyll nu i en beskrivning av dataleden. Resultatet visas som i följande exempel också taget från Budget5:

dubbelbalans; / ** 

Generera Doxygen dokumentation
Doxygen kan generera dokumentation i flera olika format, men vissa (som kompilerad HTML) kräver ytterligare nedladdningar. HTML-formatet är särskilt bekvämt eftersom det inte kräver något annat än en webbläsare att visa.
Standard är HTML, men om du vill ändra formatet väljer du DoxyBlocks → Öppna inställningar och väljer sedan fliken Doxyfile Standard 2. I det här fönstret kan du välja alla olika format som du vill skapa.
Innan du tar ut dokumentationen första gången kommer du förmodligen att välja några andra alternativ. Välj DoxyBlocks → Öppna inställningar och välj sedan fliken Doxyfile-standard. Se till att rutan Utdrag alla är markerad. Välj sedan fliken Doxyfile Standard 2 och markera kryssrutan Class_Diagrams. Välj nu fliken Allmänt och kryssrutan Kör HTML efter kompilering. Klicka på OK, och du är klar. (Du behöver inte göra det igen när alternativen sparas i en fil som heter doxyfile.)
Välj DoxyBlocks → Utdrag dokumentation för att generera och visa dokumentationen. Efter ett ganska kort intervall öppnar Doxygen din favoritbläddrare med dokumentation som det som visas i följande bild.
Doxygen är inte särskilt användarvänligt när det gäller inmatningsfel. Ibland slutar Doxygen bara att generera dokumentation någon gång i din källa utan någon uppenbar anledning.Kontrollera doxygen. loggfilen som finns i samma katalog som doxyfilen för eventuella fel som kan ha uppstått vid utvinning.
Följande bild visar projektbläddraren i det vänstra fönstret som gör att användaren kan navigera i projektets dokumentation. Till höger har funktionen getAccounts () valts för att få en mer detaljerad beskrivning. Den korta beskrivningen visas på första raden, följt av den detaljerade beskrivningen, parametrarna och returvärdet:

Klassdokumentationen är lika noggrann som visad av följande kodbit.
/ ** klasskonto * korta ett abstrakt bankkonto. * detaljer Den här abstrakta klassen innehåller * egenskaper som är gemensamma för båda kontotyperna: * Kontroll och besparingar. Det saknas emellertid * konceptuttaget (), vilket är annorlunda * mellan de två * / klasskontot {

Dokumentationen för Konto visas här:

Observera beskrivningen som visas under klass konto . Detta är den korta beskrivningen. Om du klickar på Mer tar du dig till den detaljerade beskrivningen. Observera också den grafiska representationen av arvsförhållandet mellan Konto , dess föräldraklasser och dess barnklasser.