| fb-doc 0.2 documentation tool for FreeBasic

- Main Page
- Tutorial
- Data Structures
- Files

- File List
- Globals

All Data Structures Files Functions Variables Typedefs Enumerations Enumerator Macros Pages
fb-doc_emit_doxy.bas
Go to the documentation of this file.
1 /'* \file fb-doc_emit_doxy.bas
2 \brief Emitter for Doxygen templates
3
4 This file contains emitter functions for the \ref EmitterIF to
5 generate template blocks for the Doxygen Back-end. It's designed to
6 be used in Geany mode (see section \ref exadoxy for an example).
7
8 The emitters return all original source code unchanged. Additionally
9 relevant lines (or code blocks) get prepended by a multi line block
10 of documentation. This works for SUBs/FUNCTIONs, TYPE, UNION and
11 ENUM blocks, declarations (VAR / DIM / CONST / COMMON / EXTERN /
12 STATIC) and \#DEFINEs / \#MACROs.
13
14 The block starts with the C declaration of the construct and a line
15 for the brief description. Then the members are listed with leading
16 param or var keyword and followed by a line for the brief
17 description. The block ends by a FIXME text for the detailed
18 description.
19
20 Since the prefered way to document variables with Doxygen is to
21 write the comment behind the variable, this emitter is mostly
22 helpful for documenting functions and their parameter lists.
23
24 When an empty line is send by Geany, the text of the doxy_empty()
25 function gets emitted. This is a comment block template to describe
26 the source file. (The text can be replaced by the context of the file
27 \em empty.txt.)
28
29 '/
30
31
32 CONST _
33 DOXY_START = NL & "/'* ", _ '*< the start of a comment block
34 DOXY_END = NL & _
35 NL & FIXME & _
36 COMM_END '*< the end of a comment block
37
38
39 /'* \brief Emitter to generate a line for a parameter list entry
40 \param P the parser calling this emitter
41
42 This emitter gets called when the parser is in a parameter list of a
43 function (SUB / FUNCTION / PROPERTY / CONSTRUCTOR / DESTRUCTOR). It
44 generates a line for each parameter and sends it (them) to the
45 output stream.
46
47 '/
48 SUB doxy_entryListPara CDECL(BYVAL P AS Parser PTR)
49 WITH *P
50 IF .NamTok THEN Code(NL & "\param " & .SubStr(.NamTok) & " " & FIXME)
51 END WITH
52 END SUB
53
54
55 /'* \brief Emitter to generate a template for a function
56 \param P the parser calling this emitter
57
58 This emitter gets called when the parser finds a function (SUB /
59 FUNCTION / PROPERTY / CONSTRUCTOR / DESTRUCTOR). It generates a
60 template to document the function and its parameter list and
61 sends it to the output stream.
62
63 '/
64 SUB doxy_func_ CDECL(BYVAL P AS Parser PTR)
65 WITH *P
66 VAR a = .SrcBgn, b = .ParTok, t = .TypTok
67 cEmitSource(P, *(.StaTok + 1))
68 Code( DOXY_START & "\fn ")
69 OPT->Function_(P)
70 Code(NL & "\brief " & FIXME)
71 IF b THEN .ParTok = b : .parseListPara(@doxy_entryListPara)
72 '& doxy_entryListPara(); // pseudo function call (helps Doxygen documenting the interface)
73 IF t THEN Code(NL & "\returns: " & FIXME)
74 Code(DOXY_END)
75 .SrcBgn = a
76 END WITH
77 END SUB
78
79
80 /'* \brief Emitter to generate a template for a declaration
81 \param P the parser calling this emitter
82
83 This emitter gets called when the parser is in a declaration (VAR /
84 DIM / CONST / COMMON / EXTERN / STATIC). It generates a line for
85 each variable name and sends it (them) to the output stream.
86
87 '/
88 SUB doxy_decl_ CDECL(BYVAL P AS Parser PTR)
89 WITH *P
90 IF 0 = .ListCount THEN
91 cEmitSource(P, *(.StaTok + 1))
92 Code(DOXY_START)
93
94 IF .FunTok THEN Code("\fn ") _
95 ELSE Code("\var ")
96
97 SELECT CASE AS CONST *.StaTok
98 'CASE .TOK_CONS : Code("const ")
99 'CASE .TOK_STAT : Code("static ")
100 'CASE .TOK_COMM : Code("common ")
101 'CASE .TOK_EXRN : Code("extern ")
102 CASE .TOK_CONS,.TOK_STAT, .TOK_COMM, .TOK_EXRN
103 IF OPT->Types = OPT->C_STYLE THEN Code(LCASE(.SubStr(.StaTok)) & " ") _
104 ELSE Code( .SubStr(.StaTok) & "_")
105 CASE .TOK_TYPE : Code("typedef ")
106 IF 0 = .FunTok ANDALSO .TypTok > .NamTok THEN Code("struct ")
107 END SELECT
108 END IF
109
110 IF .FunTok THEN
111 VAR a = .SrcBgn, b = .ParTok, t = .TypTok
112 OPT->Function_(P)
113 Code(NL & "\brief " & FIXME)
114 IF b THEN .ParTok = b : .parseListPara(@doxy_entryListPara)
115 '& doxy_entryListPara(); // pseudo function call (helps Doxygen documenting the interface)
116 IF t THEN Code(NL & "\returns: " & FIXME)
117 Code(DOXY_END)
118 .SrcBgn = a
119 Code("'' " & PROG_NAME & "-hint: consider to document the functions body instead." & NL)
120 ELSEIF .TypTok THEN
121 OPT->Variable_(P)
122 Code(NL & "\brief " & FIXME & DOXY_END)
123 ELSE
124 IF 0 = .ListCount THEN Code("VAR ")
125 Code(.SubStr(.NamTok))
126 IF .IniTok THEN Code(" " & .VarIni)
127 Code(NL & "\brief " & FIXME & DOXY_END)
128 END IF
129 END WITH
130 END SUB
131
132
133 /'* \brief Emitter to generate a templates for a macro
134 \param P the parser calling this emitter
135
136 This emitter gets called when the parser finds a macro (\#DEFINE /
137 \#MACRO). It generates a template to document the macro and sends it
138 to the output stream.
139
140 '/
141 SUB doxy_defi_ CDECL(BYVAL P AS Parser PTR)
142 WITH *P
143 cEmitSource(P, *(.StaTok + 1))
144 Code( DOXY_START & "\def " & .SubStr(.NamTok) & _
145 NL & "\brief " & FIXME & _
146 DOXY_END)
147 END WITH
148 END SUB
149
150
151 /'* \brief Emitter to generate a line for a block entry
152 \param P the parser calling this emitter
153
154 This emitter gets called when the parser is in a block (TYPE / ENUM
155 / UNION). It generates a line for each member and sends it (them) to
156 the output stream.
157
158 '/
159 SUB doxy_emitBlockNames CDECL(BYVAL P AS Parser PTR)
160 WITH *P
161 SELECT CASE AS CONST *.Tk1
162 CASE .TOK_PRIV, .TOK_PROT ': .SrcBgn = 0 ' !!! ToDo: hide private?
163 CASE .TOK_PUBL ': .SrcBgn = 1
164 CASE .TOK_CLAS, .TOK_TYPE, .TOK_UNIO
165 .parseBlockTyUn(@doxy_emitBlockNames)
166 CASE .TOK_ENUM
167 .parseBlockEnum(@doxy_emitBlockNames)
168 CASE ELSE : IF 0 = .NamTok THEN EXIT SUB
169 Code(NL & "\var " & .BlockNam & "::" & .SubStr(.NamTok) & " " & FIXME & _
170 NL & "\brief " & FIXME)
171 END SELECT
172 '& doxy_emitBlockNames(); // pseudo function call (helps Doxygen documenting the interface)
173 END WITH
174 END SUB
175
176
177 /'* \brief Emitter to generate templates for blocks
178 \param P the parser calling this emitter
179
180 This emitter gets called when the parser finds a block (TYPE / UNION
181 / ENUM). It generates a template to document the block with one line
182 for each member and sends it to the output stream.
183
184 '/
185 SUB doxy_Block CDECL(BYVAL P AS Parser PTR)
186 WITH *P
187 cEmitSource(P, *(.StaTok + 1))
188 SELECT CASE AS CONST *.Tk1
189 CASE .TOK_ENUM
190 Code( DOXY_START & "\enum " & .BlockNam & _
191 NL & "\brief " & FIXME & _
192 NL & _
193 NL & FIXME & _
194 NL)
195 .parseBlockEnum(@doxy_emitBlockNames)
196 CASE .TOK_UNIO
197 Code( DOXY_START & "\union " & .BlockNam & _
198 NL & "\brief " & FIXME & _
199 NL & _
200 NL & FIXME & _
201 NL)
202 .parseBlockTyUn(@doxy_emitBlockNames)
203 CASE ELSE
204 Code( DOXY_START & "\class " & .BlockNam & _
205 NL & "\brief " & FIXME & _
206 NL & _
207 NL & FIXME & _
208 NL)
209 .parseBlockTyUn(@doxy_emitBlockNames)
210 END SELECT
211 '& doxy_emitBlockNames(); // pseudo function call (helps Doxygen documenting the interface)
212 Code(COMM_END)
213 END WITH
214 END SUB
215
216
217 /'* \brief Emitter for an empty Geany block
218 \param P the parser calling this emitter
219
220 This emitter gets called when an empty block gets send by Geany and
221 no file \em Empty.txt exists. The emitter generates a template to
222 document the source file and sends it to the output stream.
223
224 '/
225 SUB doxy_empty CDECL(BYVAL P AS Parser PTR)
226 WITH *P
227 Code( DOXY_START & "\file " & FIXME & _
228 NL & "\brief " & FIXME & _
229 DOXY_END)
230 END WITH
231 END SUB
232
233
234 WITH_NEW_EMITTER("DoxygenTemplates")
235 ._Error_ = @c_error ' we use the standard error emitter here
236
237 .Func_ = @doxy_func_
238 .Decl_ = @doxy_decl_
239 .Defi_ = @doxy_defi_
240 .Enum_ = @doxy_Block
241 .Unio_ = @doxy_Block
242 .Clas_ = @doxy_Block
243 ._Init_ = @geanyInit ' ... and the Geany init / exit functions
244 ._Exit_ = @geanyExit
245 ._Empty_ = @doxy_empty
246 END WITH
247