C ++: Documentatie maken met Doxygen - dummies

De meeste programmeurs haten het om nog meer documentatie te maken dan dat ze een hekel hebben aan hun eigen code. Voer Doxygen in, waarmee programmeurs tags kunnen insluiten in de opmerkingen die later kunnen worden geëxtraheerd om de documentatie te maken.

Doxygen installeren

Doxygen wordt niet geleverd met Code:: Blocks (althans niet vanaf dit moment). U moet de juiste versie van Doxygen voor uw toepassing downloaden. (Er is ook een link naar de Doxygen-website vanuit de code:: Blokkeert de site.) Nadat u naar de Doxygenorg-website hebt gelinkt, kunt u naar de downloadpagina gaan en de versie van Doxygen voor uw besturingssysteem vinden, zoals hier wordt weergegeven:

Download en installeer de versie die geschikt is voor uw besturingssysteem. U kunt de standaardinstellingen accepteren, maar onthoud waar de installatiewizard het Doxygen-uitvoerbare bestand plaatst.

Start nu Code:: Blokken. Selecteer DoxyBlocks → Open voorkeuren. Vanaf daar selecteert u het tabblad Algemeen en stelt u het pad naar Doxygen in. (Dit is het pad dat u in de vorige paragraaf hebt genoteerd.) Het standaardpad voor Windows is C: Program FilesDoxygenbindoxygen. exe. Doe hetzelfde voor het pad naar Doxywizard. Hier is de standaardwaarde voor Windows C: Program FilesDoxygenbindoxywizard. exe . U kunt de andere gereedschappen leeg laten omdat ze niet nodig zijn bij het genereren van documentatie in HTML-indeling.

Opmerkingen over documentatie toevoegen

Doxygen gebruikt speciale opmerkingen om zoekwoorden te markeren die helpen bij het maken van documentatie. Verwarrend genoeg accepteert Doxygen verschillende standaarden, maar de standaard is degene die het meest op JavaDoc lijkt, de / ** opmerking, en dat is prima. (U kunt de commentaarstijl wijzigen in een van de anderen door DoxyBlocks → Open voorkeuren te selecteren en vervolgens het tabblad Comment Style te selecteren.)

Om te zien hoe dit werkt, plaatst u de cursor aan het begin van een functie en selecteert u DoxyBlocks → Reactie blokkeren (of drukt u op Ctrl + Alt + B). Een opmerking zoals het volgende verschijnt (de volgende voorbeelden gebruiken het Budget5-programma dat verschijnt in het downloadbare materiaal op www. Dummies. Com / extras / cplusplus):

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

Code:: Blokken voegt een Doxygen-blokcommentaar toe beginnend met / **. Doxygen weet dat deze opmerking behoort tot de functiedefinitie die onmiddellijk volgt. Doxygen-zoekwoorden beginnen met een (backslash). Het korte trefwoord markeert de korte beschrijving van de functie. De korte beschrijving kan zich uitstrekken over meer dan één regel.Dit zou een korte beschrijving moeten zijn van de functie die in tabellarische displays wordt weergegeven.

De programmeur kan dit volgen met een grondiger beschrijving gemarkeerd met het sleutelwoord details . Deze gedetailleerde beschrijving geeft een meer grondige beschrijving van wat de functie doet.

Veel van de Doxygen-zoekwoorden zijn optioneel. In het bijzonder wordt het detail zoekwoord verondersteld als u een alinea scheidt van de korte beschrijving door niets meer dan een lege regel.

Verder is er een aparte regel gemarkeerd met het trefwoord param om elk argument voor de functie te beschrijven. Het trefwoord retourneert ten slotte beschrijft de waarde die door de functie wordt geretourneerd.

Bij het invullen kan de Doxygen-opmerking voor getAccounts () als volgt verschijnen:

/ ** beknopte getAccounts - voert accounts van het toetsenbord in * details Deze functie leest de invoer via het toetsenbord. * Voor elke S of C die wordt ingevoerd, maakt de functie een nieuw * spaar- of controleaccountobject aan en voegt dit toe aan de * accountlijst. Een X beëindigt de invoer. Elke andere * -input wordt verondersteld een aanbetaling te zijn (getallen groter dan * 0) of een opname (getallen kleiner dan 0). * * param accLijst en de lijst met account * -objecten gemaakt door getAccounts () * return void * / void getAccounts (list & accList) {

U kunt ook een Doxygen-opmerking toevoegen op dezelfde regel. Dit wordt meestal gebruikt bij het beoordelen van gegevensleden. Plaats de cursor aan het einde van de regel en selecteer DoxyBlocks → Regelopmerking of druk op Ctrl + Alt + L. Vul nu een beschrijving van het gegevenslid in. Het resultaat wordt weergegeven zoals in het volgende voorbeeld ook uit Budget5:

dubbele balans; / ** 

Doxygen-documentatie genereren
Doxygen kan documentatie in verschillende indelingen genereren, hoewel sommige (zoals gecompileerde HTML) verdere downloads vereisen. Het HTML-formaat is bijzonder handig omdat het niets meer dan een browser nodig heeft om te bekijken.
De standaardinstelling is HTML, maar als u de indeling wilt wijzigen, selecteert u DoxyBlocks → Open voorkeuren en vervolgens het tabblad Doxyfile Defaults 2. In dit venster kunt u alle verschillende indelingen selecteren die u wilt genereren.
Voordat u de documentatie voor de eerste keer uitpakt, wilt u waarschijnlijk een paar andere opties selecteren. Selecteer DoxyBlocks → Open voorkeuren en vervolgens het tabblad Doxyfile-standaardinstellingen. Zorg ervoor dat het vakje Alles extraheren is aangevinkt. Selecteer vervolgens het tabblad Doxyfile Defaults 2 en vink het selectievakje Class_Diagrams aan. Selecteer nu het tabblad Algemeen en vink het vakje Run HTML After Compilation aan. Klik op OK, en je bent klaar. (U hoeft dit niet opnieuw te doen omdat de opties worden opgeslagen in een bestand met de naam doxyfile.)
Selecteer DoxyBlocks → Documentatie extraheren om de documentatie te genereren en te bekijken. Na een vrij kort interval opent Doxygen je favoriete browser met documentatie zoals getoond in de volgende afbeelding.
Doxygen is niet erg gebruiksvriendelijk als het gaat om invoerfouten. Soms stopt Doxygen met het genereren van documentatie op een bepaald punt in je bron zonder duidelijke reden.Controleer de doxygen. logbestand in dezelfde map als het doxy-bestand voor eventuele fouten die tijdens de extractie zijn opgetreden.
De volgende afbeelding toont de projectbrowser in het linkervenster waarmee de gebruiker kan navigeren binnen de projectdocumentatie. Aan de rechterkant is de functie getAccounts () geselecteerd om een ​​meer gedetailleerde beschrijving te krijgen. De korte beschrijving verschijnt op de eerste regel, gevolgd door de gedetailleerde beschrijving, de parameters en de geretourneerde waarde:

De klassedocumentatie is even grondig als weergegeven in het volgende codefragment.
/ ** class Account * brief een abstracte bankrekening. * details Deze abstracte klasse bevat * eigenschappen die horen bij beide accounttypen: * Controleren en besparingen. Er ontbreekt echter de * concept-intrekking (), die anders is * tussen de twee * / class-account {

De documentatie voor Account wordt hier weergegeven:

Let op de beschrijving die wordt weergegeven onder de class account . Dit is de korte beschrijving. Als u op Meer klikt, gaat u naar de gedetailleerde beschrijving. Let ook op de grafische weergave van de overervingsrelatie tussen Account , de bovenliggende klassen en de onderliggende klassen.