C ++: Opprette dokumentasjon med Doxygen-dummies

De fleste programmører hater å lage dokumentasjon enda mer enn de hater å kommentere sin egen kode. Skriv inn Doxygen, som gjør det mulig for programmerere å legge inn koder i kommentarene som senere kan hentes for å lage dokumentasjonen.

Installere Doxygen

Doxygen kommer ikke med kode:: Blokker (i hvert fall ikke som i denne skrivingen). Du må laste ned den riktige versjonen av Doxygen for din søknad. (Det er også en lenke til Doxygen-nettstedet fra Koden:: Blokker-siden.) Etter at du har koblet til Doxygenorg-nettstedet, kan du navigere til nedlastingssiden og finne versjonen av Doxygen for operativsystemet ditt, som vist her:

Last ned og installer versjonen som passer for operativsystemet. Du kan godta standardinnstillingene, men husk hvor installasjonsveiviseren plasserer Doxygen-kjørbar fil.

Start nå Kode:: Blokker. Velg DoxyBlocks → Åpne innstillinger. Derfra velger du kategorien Generelt og angir banen til Doxygen. (Dette er banen du merket i forrige avsnitt.) Standardbanen for Windows er C: Program Filesdoxygenbindoxygen. exe. Gjør det samme for banen til Doxywizard. Her er standard for Windows C: Program Filesdoxygenbindoxywizard. exe . Du kan la de andre verktøyene være tomme som de ikke trengs når du genererer dokumentasjon i HTML-format.

Legge til dokumentasjonskommentarer

Doxygen bruker spesielle kommentarer til å flagge søkeord som hjelper verktøyet til å opprette dokumentasjon. Forvirrende nok, aksepterer Doxygen flere forskjellige standarder, men standard er den som ser mest ut som JavaDoc, / ** kommentaren, som er greit. (Du kan endre kommentarstilen til en av de andre ved å velge DoxyBlocks → Åpne innstillinger og deretter velge fanen Kommentarstil.)

For å se hvordan dette virker, plasser markøren i begynnelsen av en funksjon og velg DoxyBlocks → Block Comment (eller trykk Ctrl + Alt + B). En kommentar som følgende vises (følgende eksempler bruker Budget5-programmet som vises i nedlastbart materiale på www. Dummies.com / extras / cplusplus):

/ ** kort * * param accList list & * return void * * / ugyldige getAccounts (liste og akkreditering) {

Kode:: Blokker innfører en Doxygen-blokkkommentar med start med / **. Doxygen vet at denne kommentaren tilhører funksjonsdefinisjonen som umiddelbart følger. Doxygen søkeord starter med en (tilbakeslag). kort søkeordet flagger den korte beskrivelsen av funksjonen. Den korte beskrivelsen kan strekke seg over flere linjer.Dette bør være en kort beskrivelse av funksjonen som vises i tabellskjermbildet.

Programmereren kan følge dette med en grundigere beskrivelse som er merket med detaljer søkeord. Denne detaljerte beskrivelsen gir en grundigere beskrivelse av hva funksjonen gjør.

Mange av Doxygen-søkeordene er valgfrie. Spesielt er detaljer nøkkelordet antatt hvis du starter et avsnitt som er skilt fra kort -beskrivelsen, med ingenting mer enn en tom linje.

Utover det er en egen linje merket med søkeordet param for å beskrive hvert argument til funksjonen. Endelig beskriver retur søkeord verdien som returneres av funksjonen.

Når du fyller ut, kan Doxygen-kommentaren for getAccounts () vises som følger:

/ ** kort getAccounts - skriver inn kontoer fra tastaturet * detaljer Denne funksjonen leser innspill fra tastaturet. * For hver S eller C som er oppgitt, oppretter funksjonen et nytt * Savings eller Checking-kontoobjekt og legger det til * kontolisten. En X avslutter oppføringen. Enhver annen * inngang antas å være et innskudd (tall større enn * 0) eller en tilbaketrekking (tall mindre enn 0). * * param accList liste og listen over konto * objekter opprettet av getAccounts () * return void * / void getAccounts (liste og akkreditering) {

Du kan også legge til en Doxygen-kommentar på samme linje. Dette brukes oftest når man kommenterer data medlemmer. Plasser markøren på slutten av linjen, og velg enten DoxyBlocks → Line Kommentar eller trykk Ctrl + Alt + L. Nå fyll ut en beskrivelse av datalederen. Resultatet vises som i følgende eksempel også tatt fra Budsjett5:

dobbeltbalanse; / ** 

Generering Doxygen dokumentasjon
Doxygen kan generere dokumentasjon i flere forskjellige formater, selv om noen (som kompilert HTML) krever ytterligere nedlastinger. HTML-formatet er spesielt praktisk fordi det ikke krever noe mer enn en nettleser for å vise.
Standard er HTML, men hvis du vil endre formatet, velg DoxyBlocks → Åpne preferanser, og velg deretter kategorien Doxyfile Standard 2. I dette vinduet kan du velge alle de forskjellige formatene du vil generere.
Før du utvinner dokumentasjon første gang, vil du sannsynligvis ønske å velge noen andre alternativer. Velg DoxyBlocks → Åpne innstillinger, og velg deretter kategorien Doxyfile-standard. Kontroller at boksen Utdrag alle er merket. Deretter velger du kategorien Doxyfile Standard 2 og merker av for Class_Diagrams. Velg kategorien Generelt og merk av for Run HTML After Compilation. Klikk på OK, og du er ferdig. (Du trenger ikke å gjøre dette igjen når alternativene er lagret i en fil som heter doxyfile.)
Velg DoxyBlocks → Utdrag dokumentasjon for å generere og vise dokumentasjonen. Etter et ganske kort mellomrom åpner Doxygen din favoritt nettleser med dokumentasjon som vist i den følgende figuren.
Doxygen er ikke veldig brukervennlig når det gjelder inngangsfeil. Noen ganger slutter Doxygen bare å generere dokumentasjon på et tidspunkt i kilden din uten noen åpenbar grunn.Sjekk doxygen loggfilen som finnes i samme katalog som doxyfilen for eventuelle feil som kan ha oppstått under utvinning.
Følgende bilde viser prosjektleseren i venstre vindu som lar brukeren navigere i prosjektets dokumentasjon. Til høyre har funksjonen getAccounts () blitt valgt for å få en mer detaljert beskrivelse. Den korte beskrivelsen vises på første linje, etterfulgt av detaljert beskrivelse, parametrene og returverdi:

Klassedokumentasjonen er like grundig som vist med følgende kodestykke.
/ ** klasse konto * kort en abstrakt bankkonto. * detaljer Denne abstrakte klassen inneholder * egenskaper som er felles for begge kontotyper: * Kontroll og besparelser. Det mangler imidlertid * konseptets tilbaketrekking (), som er forskjellig * mellom de to * / klassekontoen {

Dokumentasjonen for Konto vises her:

Merk beskrivelsen som vises under klasse konto . Dette er den korte beskrivelsen. Hvis du klikker på Mer, tar du deg til den detaljerte beskrivelsen. Legg også merke til den grafiske representasjonen av arveforholdet mellom Konto , dets foreldreklasser og dets barnklasser.