-
Notifications
You must be signed in to change notification settings - Fork 0
/
README.doxygen
109 lines (87 loc) · 4 KB
/
README.doxygen
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
-------------------------
DOCUMENTAZIONE -- doxygen
-------------------------
Doxygen e un sistema di documentazione utilizzabile per un insieme di
linguaggi (C++,C,Java,Phyton ... etc), vedi
http://en.wikipedia.org/wiki/Doxygen
e
http://www.doxygen.org
Manuale online:
http://www.stack.nl/~dimitri/doxygen/manual.html
Come Javadoc, doxygen estrae documentazione dai commenti nel file sorgente, ma
puo' generare output in diversi formati: HTML ma anche CHM, RTF, PDF, LaTeX,
PostScript o man pages.
Doxygen ha bisogno di un file di configurazione che serve per interpretare il
formato dei commenti.
Dopodiche' il comando "doxygen" parsa i file sorgenti seguendo le istruzioni
nel file di configurazione e genera la documentazione secondo il formato
specificato dal file di configurazione (puo' essere HTML, latex, man pages
etc...)
1) Creare il file di configurazione ##############
bash:~$ doxygen -g [name_conf_file]
crea un template da personalizzare. Il template puo' essere editato con un
normale editor o con doxywizard (una GUI piu' user friendly).
il formato del file di configurazione e' quello di un semplice makefile con
una serie di assegnamenti (tags) della forma:
TAGNAME = VALUE or
TAGNAME = VALUE1 VALUE2 ...
Per progetti standard la maggior parte dei tag si possono lasciare a valore di
default. Per i progetti semplici, tutti nella stessa directory, il tag INPUT
puo' essere lasciato vuoto. Alternatimente deve essere la radice dell'albero da
parsare ed anche il tag RECURSIVE deve essere settato. Inoltre e' possibile
specificare le estensioni dei file da parsare etc (i .c .h sono parsati di
default).
Per maggiori dettagli su tutti i tag vedi:
http://www.stack.nl/~dimitri/doxygen/config.html
2) Girare Doxygen ###############
Una volta generato il file di configurazione basta girare
bash:~$ doxygen <config-file>
(se il nome e' Doxyfile, non importa specificarlo)
A questo punto a seconda di quanto specificato nel file vengono create delle
directory html, rtf, latex, xml e/o man nella directory specificata come output
(OUTPUT tag, di default quella corrente) Che contengono la documentazione nei
formati richiesti.
3) Documentare i sorgenti #################3
Ci sono due modi di documentare:
1) in un commento immediatamente prima di qualcosa (in questo caso e' inteso
che il commento documenta cio' che segue ...)
2) in un commento in un qualsiasi altro posto. In questo caso si devono usare
dei comandi espliciti per legare il blocco di documentazione con il suo
oggetto. Alcuni comandi:
# \struct to document a C-struct.
# \union to document a union.
# \enum to document an enumeration type.
# \fn to document a function.
# \var to document a variable or typedef or enum value.
# \def to document a #define.
# \typedef to document a type definition.
# \file to document a file.
Attenzione:
si puo' usare anche la sintassi Javadoc-like con un at ('@') al posto del
backslash ('\'). es @file, @enum, @typedef etc ...
I blocchi di documentazione doxygen possono essere inglobati in commenti con
diversi formati (vedi
http://www.stack.nl/~dimitri/doxygen/docblocks.html#specialblock). Noi useremo
quelli C-like
/**
* ... testo ....
*/
Attenzione: il doppio asterisco iniziale e' ESSENZIALE, altrimenti e' un
normale commento C.
I comandi che possono essere usati nel testo del blocco sono documentati
in: http://www.stack.nl/~dimitri/doxygen/commands.html
Anche in questo caso si puo' usare anche la sintassi Javadoc-like con un at
('@') al posto del backslash ('\'). es @param, @return, @bug etc ...
Esempio (dalla documentazione on line)
/** \function WindowsNT
* \brief Windows Nice Try.
* \author Bill Gates
* \author Several species of small furry animals gathered together
* in a cave and grooving with a pict.
* \version 4.0
* \date 1996-1998
* \bug It crashes a lot and requires huge amounts of memory.
* \bug The function introduces the more bugs, the longer it is used.
* \warning This function may explode in your face.
* \warning If you inherit anything from this class, you're doomed.
*/