Kode-værkstedet 1: Doxygen
Over de sidste mange uger har jeg haft ALT for meget arbejde. En stor del af dette har været fokuseret på en stor bunke C/C++ kode, hvor jeg har arbejdet med en del forskellige SW-væktøjer, som jeg har haft stor glæde af. Disse vil jeg gerne præsentere i dette og de kommende blog-indlæg. Læs også denne tidligere blog-post.
Hvis vi nu prikker lidt til PHK, så kan det være han kan lokkes til at skrive mere om hans "darling" blandt Lint-produkter (statisk kodeanalyse) - FlexeLint ![Eksternt billede](http://www.version2.dk/uploads/smil3dbd4d6422f04.gif" alt=")
I dette første indlæg ser jeg nærmere på Doxygen, som er et fantastisk værktøj til at give overblik over C/C++/Java/VHDL og meget andet. Ideen er at man skriver lidt struktureret dokumentation i sin kode løbende, og derefter anvender doxygen til at give HTML, LaTeX, eller RTF dokumentation af koden med funktionsbeskrivelser, funktions-kaldetræer og meget andet. Jeg viser lidt af dette med et eksempel, som kan findes på min web-server: http://petertoft.dk/v2/doxygen/
I C-eksemplet har jeg i modsætning til min "rigtige kode" kun fire filer, som kan ses på files.html siden. Min main()-funktion kalder et par underfunktioner, der (typisk) hver kalder et par andre underfunktioner. Man kan sætte sig og tegne funktions-hierarkiet manuelt, men det er (bl.a.) her doxygen virkelig er guld værd. Jeg starter med at installe doxygen og graphviz pakkerne på min Linux-maskine.
Jeg har været doven og anvendt den grafisk front-end til doxygen, dvs. doxywizard:
Her kan man komme langt alene med wizard knappen, men der er et par fine muligheder under "Expert" jeg har sat til.
- Source browser: SOURCE_BROWSER + INLINE_SOURCES
- Dot: CALL_GRAPH + CALLER_GRAPH
<br/>
Med SOURCE_BROWSER + INLINE_SOURCES får jeg kildekoden [direkte ind i dokumentationen](http://petertoft.dk/v2/doxygen/code2_8c-source.html) - rigtig fint.
Med Dot: CALL_GRAPH og CALLER_GRAPH får jeg funktions-afhængighedsgrafer såsom denne lavet automagisk. RIGTIG rart!
![Eksternt billede](http://petertoft.dk/v2/doxygen/main_8c_840291bc02cba5474a4cb46a9b9566fe_..." alt="doxygen)
Bemærk at man kan klikke på HTML sidernes billeder og hoppe rundt mellem funktionerne. Det er godt lavet.
Og for alle funktioner genereres endda med min opsætning diagrammer af hvilken funktion, der kalder f.eks. fct4() - nemlig fct3() og fct_local().
![Eksternt billede](http://petertoft.dk/v2/doxygen/code2_8c_365a973b71a4cd3e24682a61c1ac0210..." alt="doxygen)
I er meget velkomne til at skrive om andre features ved doxygen. Bl.a. har jeg ikke gjort så meget ud af de glimrende muligheder, der er i doxygen for at dokumentere, men nærmere fokuseret på at få overblik over koden.
I kan hente mit kode-eksempel fra [denne URL](http://petertoft.dk/v2/version2_9173.zip). Kør doxygen for at lave HTML output svarende til [dette](http://petertoft.dk/v2/doxygen/). I kan se flere eksempler på brugen af doxygen på [denne URL](http://www.stack.nl/~dimitri/doxygen/results.html).
/pto
Om Peter ToftPeter Toft er senior specialist hos Renesas Mobile og har blogget om open source og Linux siden Version2's begyndelse. Blogger også jævnligt om andre sjove teknologi-områder.
Follow @petertoftKommentarer (9)
Doxygen er suverænt.
Også hvis man har "gamle" udokumenterede programmer.
Det er muligt at indlejre kommentarer, dokumentation osv osv
Hvis folk vil lade være med at flame mig pga skod kode så prøv at kigge på http://www.control.aau.dk/~jdn/doxygen/html/
Bla er pakken mscgen til selens diagrammer ret smart/enkel.
\msc
hscale = "0.4";
a,b,c;
a->b [ label = "ar_fct", URL="\ref ar_fct" ] ;
b->c [ label = "bc(TRUE)"];
c=>c [ label = "process(1)" ];
c=>c [ label = "process(2)" ];
...;
c=>c [ label = "process(n)" ];
c=>c [ label = "process(END)" ];
a<<=c [ label = "callback()"];
--- [ label = "If more to run", ID="*" ];
a->a [ label = "next()"];
a->c [ label = "ac1()\nac2()"];
b<-c [ label = "cb(TRUE)"];
b->b [ label = "stalled(...)"];
a<-b [ label = "ab() = FALSE"];
\endmsc
once more
\msc
Sender,Receiver;
Sender->Receiver [label="Command()", URL="\ref Receiver::Command()"];
Sender<-Receiver [label="Ack()", URL="\ref Ack()", ID="1"];
\endmsc
laver de "flotte " diagrammer på forsiden.
/J
-
0 -
0
Noget jeg selv synes er snedigt er at lægge et kald til Doxygen ind i et post-commit hook i Subversion. På den måde har man altid opdateret dokumentationen til at afspejle den seneste version af koden.
-
0
-
0
Jeg må indrømme at jeg kun sjældent bruger doxygen og de skyldes at jeg mangler ihverfald to-tre dimensioner af koden i det output doxygen genererer.
Men det er da meget praktisk at kunne få en call[er]-graph produceret lidt nemt.
Men det der fis med at sprede en novelle ud over kildeteksten, det tænder jeg fuldstændig af på.
Poul-Henning
-
0
-
0
Jeg er helt enig med det i at man ikke skal møje kildeteksten til, men man kan samle docu i enkelte filer så man har det samlet og det hele hænger sammen.
Jeg har haft stor glæde at doxygen til at danne mig et overblik over andres kode, selvom det som alt andet jo selvfølgelig og heldigvis ikke er den hellige gral ;-)
Men smag og behag er forskellig - heldigvis :-)
-
0
-
0
Baaaaa - doxygen napper den dokumentation, du alligevel burde lave i din kode.
MVH fra vores blogger møde (god mam)
-
0
-
0
Det er ikke korrekt - heldigvisd :-)
Groft sagt fortolker doxygen kun kommentarfelter der starter i position 1 med /** eller /*! eller /// for C++
Så en kommentar som
/* hvis der er en bug her saa giver jeg oel */
kommer ikke med
men
/** hvis der er en bug skal I give mgi en oel */
kommer med :-)
Men helt enig det er ikke den hellige gral
-
0
-
0
å¨åhh den her tingest æder spaces så der burde staa
<space><space><space>/* OEL NU */
kommer ikke med men
/** postevandnutildetoerstige */
kommer med :-)
-
0
-
0
Hvis man gerne vil have automatiseret dokumentationsprocessen med doxygen, kan man følge denne opskrift:
http://www.bioinf.uni-freiburg.de/~mmann/HowTo/automake.html#doxygenSupport
-
0
-
0
