| 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_gtk.bas
Go to the documentation of this file.
1 /'* \file fb-doc_emit_gtk.bas
2 \brief Emitter for gtk-doc templates
3
4 This file contains the emitter for gtk-doc templates. The emitter is
5 designed to create documentation comment blocks for the gtk-doc
6 back-and and it's designed to be used in Geany mode (see section \ref
7 exagtkdoc for an example).
8
9 The emitter returns all original source code. Relevant lines (or
10 code blocks) get prepended by a multi line block of documentation.
11 This works for SUBs/FUNCTIONs, TYPE, UNION and ENUM blocks and
12 \#DEFINEs / \#MACROs.
13
14 The first line of the comment block contains the name of the
15 construct, appended by a colon. Then the members are listed with a
16 leading @ character (parameters in case of a SUB / FUNCTION or
17 member variables in case of a block). The block ends by a FIXME text
18 and a line with a since keyword.
19
20 When an empty line is send by Geany, a comment block template to
21 describe the file gets emitted. (The text can be replaced by the
22 context of the file empty.txt.)
23
24 '/
25
26
27 CONST _
28 SINCE = NL & NL & "Since: 0.0", _ '*< text added at each block end
29 GTK_START = "/'* ", _ '*< the start of a comment block
30 GTK_END = NL & _
31 NL & FIXME & _
32 SINCE & _
33 COMM_END '*< the end of a comment block
34
35
36 /'* \brief Emitter to generate a name line
37 \param P the parser calling this emitter
38
39 Generate a name for a gtk-doc template. Used in lists (parameters or
40 variable declarations) or blocks (ENUM, TYPE, UNION). It generates a
41 line to document the variable and sends it to the output stream.
42
43 '/
44 SUB gtk_emit_Name CDECL(BYVAL P AS Parser PTR)
45 WITH *P
46 IF .NamTok THEN Code(NL & "@" & P->SubStr(P->NamTok) & ": " & FIXME)
47 END WITH
48 END SUB
49
50
51 /'* \brief Emitter to generate a macro template
52 \param P the parser calling this emitter
53
54 This emitter gets called when the parser finds a macro (\#DEFINE /
55 \#MACRO). It generates a template to document the macro and sends it
56 to the output stream.
57
58 '/
59 SUB gtk_defi_ CDECL(BYVAL P AS Parser PTR)
60 WITH *P
61 cEmitSource(P, *(.StaTok + 1))
62 Code(GTK_START & .SubStr(.NamTok) & ":" & GTK_END)
63 END WITH
64 END SUB
65
66
67 /'* \brief Emitter to generate a template for a declaration
68 \param P the parser calling this emitter
69
70 This emitter gets called when the parser is in a declaration (VAR /
71 DIM / CONST / COMMON / EXTERN / STATIC). It generates a line for
72 each variable name and sends it (them) to the output stream.
73
74 '/
75 SUB gtk_decl_ CDECL(BYVAL P AS Parser PTR)
76 WITH *P
77 IF 0 = .ListCount THEN
78 cEmitSource(P, *(.Tk1 + 1))
79 Code(GTK_START & .SubStr(.NamTok) & ":")
80 END IF
81
82 IF 0 = .FunTok THEN gtk_emit_Name(P) _
83 ELSE IF .ParTok THEN .parseListPara(@gtk_emit_Name)
84 '& gtk_emit_Name(); // pseudo function call (helps Doxygen documenting the interface)
85
86 IF *.CurTok > .TOK_EOS THEN EXIT SUB
87 Code(GTK_END)
88
89 IF 0 = .FunTok THEN EXIT SUB
90 Code("'' " & PROG_NAME & "-hint: consider to document the functions body instead." & NL)
91 END WITH
92 END SUB
93
94
95 /'* \brief Emitter to generate a template for a function
96 \param P the parser calling this emitter
97
98 This emitter gets called when the parser finds a function (SUB /
99 FUNCTION / PROPERTY / CONSTRUCTOR / DESTRUCTOR). It generates a
100 template to document the function and its parameter list and
101 sends it to the output stream.
102
103 '/
104 SUB gtk_func_ CDECL(BYVAL P AS Parser PTR) ' !!! ToDo member functions
105 WITH *P
106 VAR t = .TypTok
107 cEmitSource(P, *(.StaTok + 1))
108 Code(GTK_START & .SubStr(.NamTok) & ":")
109 IF .ParTok THEN .parseListPara(@gtk_emit_Name)
110 '& gtk_emit_Name(); // pseudo function call (helps Doxygen documenting the interface)
111
112 Code( _
113 NL & _
114 NL & FIXME)
115 IF t THEN Code( _
116 NL & _
117 NL & "Returns: " & FIXME)
118 Code( SINCE & _
119 COMM_END)
120 END WITH
121 END SUB
122
123
124 /'* \brief Emitter to generate a line for a block entry
125 \param P the parser calling this emitter
126
127 This emitter gets called when the parser is in a block (TYPE / ENUM
128 / UNION). It generates a line for each member and sends it (them) to
129 the output stream.
130
131 '/
132 SUB gtk_emitBlockNames CDECL(BYVAL P AS Parser PTR)
133 WITH *P
134 SELECT CASE AS CONST *.Tk1
135 CASE .TOK_PRIV, .TOK_PROT ': .SrcBgn = 0 ' !!! ToDo: hide private?
136 CASE .TOK_PUBL ': .SrcBgn = 1
137 CASE .TOK_CLAS, .TOK_TYPE, .TOK_UNIO
138 .parseBlockTyUn(@gtk_emitBlockNames)
139 '& gtk_emitBlockNames(); // pseudo function call (helps Doxygen documenting the interface)
140 CASE .TOK_ENUM
141 .parseBlockEnum(@gtk_emit_Name)
142 CASE ELSE : IF 0 = .NamTok THEN EXIT SUB
143 gtk_emit_Name(P)
144 END SELECT
145 END WITH
146 END SUB
147
148
149 /'* \brief Emitter to generate templates for blocks
150 \param P the parser calling this emitter
151
152 This emitter gets called when the parser finds a block (TYPE / UNION
153 / ENUM). It generates a template to document the block with one line
154 for each member and sends it to the output stream.
155
156 '/
157 SUB gtk_Block CDECL(BYVAL P AS Parser PTR)
158 WITH *P
159 cEmitSource(P, *(.StaTok + 1))
160 Code( GTK_START)
161 IF LEN(.BlockNam) THEN Code(.BlockNam & ":")
162
163 SELECT CASE AS CONST *.Tk1
164 CASE .TOK_ENUM : .parseBlockEnum(@gtk_emit_Name)
165 CASE ELSE : .parseBlockTyUn(@gtk_emitBlockNames)
166 END SELECT
167 '& gtk_emit_Name(); // pseudo function calls (help Doxygen documenting the interface)
168 '& gtk_emitBlockNames();
169
170 Code(GTK_END)
171 END WITH
172 END SUB
173
174
175 /'* \brief Emitter for an empty Geany block
176 \param P the parser calling this emitter
177
178 This emitter gets called when an empty block gets send by Geany and
179 no file \em Empty.txt exists. The emitter generates a template to
180 document the source file and sends it to the output stream.
181
182 '/
183 SUB gtk_empty CDECL(BYVAL P AS Parser PTR)
184 WITH *P
185 Code( GTK_START & _
186 "SECTION: " & FIXME & _
187 NL & "@short_description: " & FIXME & _
188 NL & "@title: " & FIXME & _
189 NL & "@section_id: " & FIXME & _
190 NL & "@see_also: " & FIXME & _
191 NL & "@stability: " & FIXME & _
192 NL & "@include: " & FIXME & _
193 NL & "@image: " & FIXME & _
194 GTK_END & _
195 NL)
196 END WITH
197 END SUB
198
199
200 WITH_NEW_EMITTER("GtkDocTemplates")
201 ._Error_ = @c_error '*< we use the standard error emitter here
202
203 .Func_ = @gtk_func_
204 .Decl_ = @gtk_decl_
205 .Defi_ = @gtk_defi_
206 .Enum_ = @gtk_Block
207 .Unio_ = @gtk_Block
208 .Clas_ = @gtk_Block
209 ._Init_ = @geanyInit
210 ._Exit_ = @geanyExit
211 ._Empty_ = @gtk_empty
212 END WITH
213