| 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
Tutorial.bi
Go to the documentation of this file.
1 /** \file Tutorial.bi
2 \brief Source for Tutorial pages
3
4 This file contains the context of the Tutorial pages of this
5 documentation. There's no executable source code in this file and it
6 isn't used in the fb-doc source code tree.
7
8 It's context gets included in to the documentation when Doxygen
9 scans the *. \em bi files in the \em src folder.
10
11 */
12
13 /** \page introduction Introduction
14 \tableofcontents
15
16 \section intro Introduction
17
18 In software projects it's state-of-the-art to write and edit the
19 documentation context inside the source code. This way the
20 programmer can adapt the documentation on each bug fix or
21 improvement at one place (in comments placed in the source file).
22 Beside the compiler, which extracts information for the CPU, an
23 additional tool-chain is used to extract the information from the
24 source code comments to build the documentation.
25
26 Powerful tool-chains (back-ends) exist for several programming
27 languages like C to generate output in different formats, ie like
28 \em html, \em pdf, \em man-pages and others. But privious to fb-doc
29 there is nothing for FreeBasic source code yet.
30
31 Since it's a lot of work to design and test such a tool-chain for
32 several output formats, fb-doc isn't designed as a complete tool
33 chain. Instead it works as a bridge that closes the gap between
34 FreeBasic and C syntax to make existing, well developed and tested C
35 documenting back-ends usable with FreeBasic syntax. fb-doc has been
36 tested with
37
38 - gtk-doc (see: http://developer.gnome.org/gtk-doc-manual/stable/index.html)
39
40 - Doxygen (see: http://www.doxygen.org/)
41
42 The first is a good choise if you like to document a libraries API
43 in the GNOME documentation style. In all other cases, especially
44 when you have to document a program or application, the later is the
45 better choise. Doxygen is a more modern tool, it's easier to handle,
46 comes with a GUI front-end and has more features than gtk-doc.
47
48 The steps to generate a well documented project are
49
50 -# generate source code, compile and test it
51
52 -# add documentation comments and up-date them on each change
53 inside the source code
54
55 -# run fb-doc on the FreeBasic source code to build a C-like
56 intermediate format
57
58 -# run the C-back-end on the intemediate format to build the
59 documentation output in one or more output formats (ie \em html,
60 \em pdf, \em manpage, ...)
61
62 This intermediate format doesn't contain complete C source and
63 cannot get compiled by a C compiler. Instead it just includes all
64 information the lexical scanners of the back-ends need to build the
65 documentation output. And fb-doc itself doesn't parse the complete
66 FreeBasic source code. Instead it also acts as a lexical scanner to
67 extract just the necessary information. Therefor fb-doc shouldn't be
68 executed on buggy source (, be prepared to face fancy output in that
69 case).
70
71
72 \section prinzip The Prinzip
73
74 First fb-doc has to copy the documenting comments from the FreeBasic
75 source code to the intermediate format and adapt the characters
76 starting and ending the comment from one language to the other. But
77 since some comments may only be useful in the FB source and others
78 should go to the documentation, fb-doc uses magic characters at the
79 beginning of a comment to specify how to act. FreeBasic syntax
80 allows two kinds of comments
81
82 -# line end comments starting by a ' character and ending at the
83 line end
84
85 -# comment blocks enclosed by /' and &apos;/
86
87 fb-doc supports both types. To get the comment emitted to the
88 intermediate format, its first character has to be a *. In that case
89 the context of the comment gets emitted as a similar C construct (as
90 a line end comment starting by // or as a comment block enclosed by
91 \f$/*\f$ and \f$*/\f$).
92
93 \note There's also the additional magic character '&' that makes
94 fb-doc emit the comment context as pure C-source.
95
96 See \ref exacomments for an example.
97
98 Second the lexical scanner of the back-end needs to know the target
99 of the documentation context. This can be a declaration of
100
101 - a variable (VAR / DIM / CONST / COMMON / EXTERN / STATIC),
102
103 - a memory block (ENUN / UNION / TYPE / CLASS),
104
105 - a forward declaration (TYPE alias),
106
107 - a function (SUB / FUNCTION / PORPERTY / CONSTRUCTOR / DESTRUCTOR) or
108
109 - a macro (\#DEFINE / \#MACRO).
110
111 fb-doc scans for this keywords and analyses the context. Depending
112 on the choosen emitter it generates output in a specific way. In the
113 default configuration (when acting as the start of a documentation
114 tool-chain) fb-doc translates the context to C (or C-like) source.
115
116 See \ref exadim for an example.
117
118
119 \section introadd Additional Features
120
121 In addition to this basic feature fb-doc offers further
122 functionality by adapting the operation mode and emitter:
123
124 -# It can extract a list of all function names from the source code
125 tree. The list is necessary to generate caller / callee graphs
126 with Doxygen back-end (as in this documentation), see \ref
127 backdoxy for details.
128
129 -# It can generate templates inside the FB source when acting as a
130 Geany custom command. We can mark a block of source code in
131 Geany and send it to fb-doc. fb-doc generates a matching
132 documentation comment block and prepends it to the source, see
133 \ref usagetemplates for details.
134
135 Depending on the operation mode it can input either from StdIn or
136 files and output to StdOut or files. Piping context in and from
137 fb-doc offers a lot more fields of application. In case of file
138 input / output, *.\em bas files get translated to *.\em c files and
139 *.\em bi files translate to *.\em h.
140
141 Last but not least fb-doc comes with a plugin-interface. It can load
142 and use external emitters, compiled as a dynamic loadable library (*.
143 \em dll or *.\em so). By such an external emitter modul any output
144 can get generated, using the informations comming from the fb-doc
145 scanner.
146
147 An example source code for an external emitter is in the package,
148 just customize it by your functionality. External emitter plugins
149 may add features like
150
151 - an emitter filling a data base as input for source code analysing
152 tools like <a
153 href="http://sourcenav.sourceforge.net/">sourcenavigator</a>
154
155 - an emitter to generate direct output, ie html pages
156
157 - an ...
158
159
160 \section introself About this Text
161
162 And finally some words about this documentation (the text you're
163 currently reading). It is generated from FB source in the above
164 mentioned way by using Doxygen as back-end. If you need examples for
165 any topic just study the fb-doc source code. Beside this you may
166 want to check the file \em Doxyfile in the \em src folder. It
167 contains the configuration for Doxygen to extract this pages. A
168 good start may be to use these files and create your customized
169 fb-doc documentation and play around with the parameters.
170
171 To be honest: in some cases this documentation may be a bit
172 overloaded and serve more information than necessary. But one of the
173 reasons for creating it is to demonstrate the features of fb-doc and
174 Doxygen. Therefor not all possibilities are used to reduce the
175 output to the essentials (see the Doxygen manual for details).
176
177 \note It's not under the scope of this documentation to describe the
178 usage of any (or all possible) tool-chain(s). Please refer to
179 the respective manual(s) for further information.
180
181 */
182
183
184 /** \page installation Compiling and Installing
185 \tableofcontents
186
187 fb-doc gets shipped as a FreeBasic source tree. Find the code in the
188 \em src folder of your \em fb-doc.zip archive. To create your
189 binary for your operating system just extract the folder to any
190 place on your hard disk and compile the main file
191 <em>fb-doc.bas</em>. Ie load the file in to Geany IDE and choose
192 <em>Build -> Compile</em> menu. Or call the Freebasic compiler at the
193 command line (in the extracted \em src folder)
194
195 \code fbc -w all fb-doc.bas \endcode
196
197 This creates an executable binary named
198
199 - <em>fb-doc</em> (on LINUX) or
200 - <em>fb-doc.exe</em> (on DOS / windows).
201
202 That's all you need to get started. Now you can use fb-doc and check
203 its features, translate FB code to C (ie the fb-doc source) and
204 generate templates. But &mdash; as mentioned in the prvious section
205 &mdash; fb-doc is not a complete tool-chain. To generate some
206 documentational output you additionally need a back-end for C
207 source, like
208
209 - <a href="http://developer.gnome.org/gtk-doc-manual/stable/index.html">gtk-doc</a>
210
211 - <a href="http://www.doxygen.org/">Doxygen</a>
212
213 Download one of these packages for your operating system and follow
214 the installation instruction.
215
216 There's no need to install fb-doc when you just want to find out if
217 it's helpful. For a short test just place the compiled binary in any
218 of your source folders and execute it there (see \ref usage for
219 details). Depending on the used options it may create the folder
220 <em>../doc/c_src</em> (beside your source folder) and write some
221 files in it. And it may create the file <em>fb-doc.lfn</em> in your
222 source folder (see \ref externfiles for details).
223
224 If you find out that fb-doc is useful, you may want to use it in
225 different folders and for different projects. In that case it's best
226 to install fb-doc in your system.
227
228 \section installlin LINUX Installation
229
230 It's recommended to install a batch file that calls fb-doc, because:
231
232 -# when using it as Doxygen-filter you can send additional options
233 via the batch file (Doxygen doesn't allow sending options to a
234 filter directly)
235
236 -# the batch file can call the latest fb-doc version in the source
237 folder and you're up-to-date right after compiling any up-date
238
239 This batch file should be named \em fbdoc and may look like (example
240 for bash shell, replace \em _YOUR_PATH_TO_ by a proper path)
241
242 \code
243 #! /bin/bash
244 # Start fb-doc in src folder
245
246 /home/_YOUR_PATH_TO_/fb-doc/src/fb-doc $@
247 \endcode
248
249 For a single user installation place this file in your folder
250
251 \code ~/bin \endcode
252
253 or for a system wide installation (all users, admin privileges
254 needed) place the file in any folder included in your PATH, ie in
255
256 \code /usr/bin \endcode
257
258 To execute fb-doc just type (in a shell in any folder)
259
260 \code fbdoc \endcode
261
262 and append the options you need.
263
264 \note You can test your installation by executing the above
265 command. It should output the help text.
266
267
268 \section installwoe DOS / windows Installation
269
270 Sorry, not done yet. Feel free to support the fb-doc project by
271 sending a description of your working environment.
272
273
274 \section installgeany Geany IDE Installation
275
276 fb-doc can act as a filter (= custom command) for Geany IDE. In this
277 IDE we can define several custom commands and send the currently
278 selected text to one of these commands using the menu
279 <em>Edit->Format->Send Selection to</em> (or we use the matching
280 keybinding &mdash; \em Crtl-[1, 2, 3, ...] is default). The output
281 from the custom command will be used to replace the current
282 selection. See <a
283 href="http://www.geany.org/manual/current/index.html#sending-text-through-custom-commands">Geany documentation</a> for details.
284
285 If there is no selection, Geany sends the current line. The current
286 line may be empty, so that the reciever gets just the line end
287 character.
288
289 To use fb-doc as a custom command in Geany the option \em --geany
290 has to be given in the command line. In that case fb-doc reads its
291 input from StdIn and write its output to StdOut. Depending on the
292 input two different actions are possible
293
294 - an empty input causes fb-doc to send either the context of the \em
295 empty.txt file (if exists in the current directory) or send the
296 output specified in the empty-function of the choosen emitter.
297
298 - a block containing FB source causes fb-doc to analyse the
299 context. The results for each known construct gets send to the
300 choosen emitter. Depending on the emitter, the output may be a
301 template to document this part of the source (gtk-doc and Doxygen
302 emitters are included). In case of a template emitter, the
303 original source code gets emitted unchanged right behind the
304 template block.
305
306 \note When the input doesn't contain a known construct, fb-doc
307 sends a help text.
308
309 To desribe this in a more practical way: We select some FB source in
310 Geany and send it to the fb-doc custom command. fb-doc adds
311 customized documentation comments to this block. The documentation
312 block is formated for a specific back-end and includes all symbol
313 names needed for the documentation. Next, we just need to fill the
314 entries of the auto-created block. An efficient way to document our
315 source code, see sections \ref exagtkdoc and \ref exadoxy for
316 examples.
317
318 To add fb-doc as a custom command in Geany, we use the <em>Send
319 Selection to->Set Custom Commands</em> menu item. We click on \em Add
320 to get a new item and type this command (after installing the batch
321 file, see \ref installlin)
322
323 \code fbdoc --geany \endcode
324
325 (When the batch isn't installed, we have to repalce \em fbdoc by the
326 full path and \em fb-doc.)
327
328 The \em GtkDocTemplates emitter is the default emitter in Geany
329 mode. To use another emitter we just append its name (or just parts
330 of it) behind the option \em --geany (separated by a space
331 character). fb-doc checks this text against the emitter names and
332 switches to the other emitter in case of a (non-case-sensitive)
333 match. Ie to generate templates for Doxygen we add the emitter name
334
335 \code fb-doc --geany DoxygenTemplates \endcode
336
337 and instead of the long option and name we can use short forms like
338
339 \code fb-doc -g doxy \endcode
340
341 See section \ref sectionoptions and \ref tabemitters for details.
342
343 */
344
345 /** \page usage How To Use
346 \tableofcontents
347
348 As mentioned before a auto-generated documentation consists of
349 information extracted from source code and from special comments.
350 While the source code is well defined by the FB syntax, the comments
351 need to match the syntax of the back-end in use.
352
353 So to test fb-doc and to learn about its usage and features you need
354 both, an installation of a C tool-chain and some source code with
355 documentation comments in the tool-chain's syntax.
356
357 The easiest way to get started is to use Doxygen and the fb-doc
358 sourc code. In that case you can skip the next section.
359
360
361 \section usagetemplates Generating Templates
362
363 For Doxygen back-end there's no need for generating templates. It's
364 best practise to write the documenting comment right in front of or
365 just behind the relevant construct. The only exeption is a
366 documenting comment for a function. It contains the names of the
367 variables in the parameter list.
368
369 Its different when using gtk-doc tool-chain. Here the documentation
370 context is collected in blocks. Such a block contains the name of
371 the relevant construct (ie a ENUM block) and the names of all its
372 members, followed by its decription. (Doxygen can handle such blocks
373 as well, but it isn't well supported.)
374
375 Generating such a comment block is a reasonable amount of word. Each
376 name has to get copied from the source in to the block. fb-doc can
377 do this for us.
378
379 When we use Geany IDE, we can use a convenient method by installing
380 fb-doc as Geany custom command (see \ref installgeany) and choose
381 the emitter for the tool-chain in use (\em GtkDocTemplates or \em
382 DoxygenTemplates). After loading the source, we select a block of
383 code, send it to fb-doc and we receive the original block, prepended
384 by a customized documentation block. We just need to edit the
385 entries (marked by the text \em FIXME). See \ref exagtkdoc and
386 \ref exadoxy for examples.
387
388 We can select a single construct and generate the comment blocks
389 one-by-one. Or we select a bunch of statements and fb-doc inserts
390 the templates inbetween the constructs. In case of a block
391 construct (ENUM / UNION / TYPE) it's advantageous to select the
392 complete block up to the END ... statement, to get all members
393 listed in the documentation block. In case of a function
394 decalaration the selection need not include the function body, but
395 should contain the complete decalaration.
396
397 It's a bit less convenient to auto-generate templates when an other
398 IDE is in use. In that case the documentation blocks can get
399 generated for a complete file, by piping its context to fb-doc. See
400 \ref usagepipe for details.
401
402
403 \section backgtk Gtk-doc
404
405 When using gtk-doc as back-end the documentation comment blocks are
406 placed before a structure, union, function ... and the names of the
407 members or parameters are listed in the comment block, prepended by
408 a \@ character and appended by a colon. See the manual
409 http://developer.gnome.org/gtk-doc-manual/stable/index.html for
410 details. Find an example for a gtk-doc documentation comment in \ref
411 exagtkdoc.
412
413 fb-doc helps us by creating such documentation comment blocks (=
414 template). We select a piece of code in Geany and send it to the
415 fb-doc filter. fb-doc creates a template, evaluates the names from
416 our source code and includes them in the template, followed by the
417 text \em FIXME. We just replace this text by the proper description.
418 To use this feature we have to install fb-doc as Geany filter, see
419 \ref installgeany for details.
420
421 When our documentation texts are done, we create a pseudo C source
422 tree in a separate folder and use the gtk-doc tool chain on this C
423 files. Therefor we start a command line interpreter (shell) and
424 switch to the folder where our FB source is placed. Then, we execute
425
426 \code fb-doc --asterix --fileoutput \endcode
427
428 This makes fb-doc creating a new folder <em>../doc/c_src</em> (if
429 not present) and write pseudo C files similar to our FB source
430 (overriding existing files). *.\em bas files get translated to *.\em
431 c and *.\em bi files get translated to *.\em h. Our documentation
432 comments get transfered to this files and some of our FB code gets
433 translated to C syntax. Then we start the gtk-doc tool-chain in the
434 <em>../doc/c_src</em> folder as descibed in the above mentioned
435 manual (\em gtkdoc-scan, ...).
436
437 gtk-doc works well to document a library API. Especially when it's
438 related to GLib, GTK+ or gnome software. One of the unique features
439 is auto-extracting the properties from the source code (I'll publish
440 an FB tool soon). But it's not the best choise when we want to
441 document a program like fb-doc. In that case we better use Doxygen.
442
443
444 \section backdoxy Doxygen Back-End
445
446 For Doxygen we can either use separate comment blocks, similar to
447 the gtk-doc blocks. Doxygen blocks use a different syntax and they
448 don't need to be placed in front of the related construct. fb-doc
449 also supports Doxygen templates, but this way of documenting isn't
450 very common and not well supported yet.
451
452 The other case is &mdash; a more commen way &mdash; to place the
453 documentation directly in front of (or behind the) related construct.
454 Rather than documenting a complete block at once, just the class
455 name or just one member gets documented in one comment. This way is
456 more convenient, we need not extract the names from our source code.
457 We just place the documentation beside the construct and Doxygen
458 picks the names from the source. For that way of documenting there's
459 no need to generate templates. The only execption is a parameter
460 list, where the parameter names have to be listed in the
461 documentation block. See
462
463 - the manual
464 http://www.stack.nl/~dimitri/doxygen/manual.html for details.
465 - \ref exadoxy for an example for a function comment block
466 - all fb-doc source code as further examples.
467
468 For Doxygen we can also create the pseudo C files in the
469 <em>../doc/c_src</em> folder, as described in the previous section.
470 But it's more convenient to send the pseudo C code directly to
471 Doxygen without creating intermediate files. This can be done by
472 using fb-doc as a Doxygen filter. (We use Doxygen as if we were
473 working on C source code, fb-doc translates on-the-fly when Doxygen
474 reads the input.)
475
476 Doxygen gets controlled by a configuration file. This file contains
477 all options. Here we can specify the fb-doc filter by adapting the
478 following:
479
480 First we have to tell Doxygen that it should load FB source files:
481
482 \code
483 FILE_PATTERNS = *.bi \
484 *.bas
485 \endcode
486
487 and second we need to set fb-doc as the filter for these files
488
489 \code
490 FILTER_PATTERNS = *.bas=fbdoc \
491 *.bi=fbdoc
492 \endcode
493
494 \note Doxygen doesn't allow to send additional options directly to
495 a filter. So if we need further options we can set the name
496 of a batch file here and call fb-doc from the batch file
497 passing further options.
498
499 That's it. When we now start doxygen with proper settings for the
500 paths and output format, we get our first auto-created
501 documentation. (Try it with the fb-doc source code.)
502
503 To get caller and callees graphs (as in this document) it gets a
504 little tricky. Doxygen needs the function calls inside the function
505 bodies (in the C source). But when fb-doc acts as a Doxygen filter
506 it gets restarted on each file. So it doesn't know a function
507 declaration in file B when working on file A. The names of all the
508 functions must be known to evaluate their calls in a function body
509 and to generate proper pseudo C source. That's why fb-doc reads the
510 names from a file called <em>fb-doc.lfn</em> in the current folder.
511
512 We needn't generate this file manually, fb-doc can do this for
513 us by executing the command
514
515 \code fb-doc --list \endcode
516
517 in our source folder. This writes a new (or overrides an existing) file
518 <em>fb-doc.lfn</em> in the current folder. When we don't start Doxygen
519 in our source folder, we have to move the file to the folder where
520 we execute the \em doxygen command. When we use Doxywizzard (the GUI
521 frontend for Doxygen) this is the folder specified under
522
523 \verbatim
524 Step1: Specify the working directory from which doxygen will run
525 \endverbatim
526
527 And we have to specify fb-doc as filter for source files and enable
528 source file filtering
529
530 \code
531 FILTER_SOURCE_FILES = YES
532
533 FILTER_SOURCE_PATTERNS = *.bas=fbdoc \
534 *.bi=fbdoc
535 \endcode
536
537 In the next run Doxygen should be able to generate caller and callee
538 graphs in the documentation (if the settings are correct and all
539 tools are available).
540
541 But this has a downside: when we want the source files in the
542 documentation (as in this document) the C-like code is used. To get
543 the FB code we have to run Doxygen twice:
544
545 -# without source filtering to get the \em html files with FB source
546
547 -# with source filtering to get the graphs
548
549 Before the second run we save the \em html source files in a
550 separate folder by executing in the Doxygen html output folder
551 something like (example for LINUX OS)
552
553 \code
554 mkdir bas
555 mv *bas_source.html bas
556 mv *bi_source.html bas
557 \endcode
558
559 and after the second run we restore the FB source files
560
561 \code
562 rm *bas_source.html
563 rm *bi_source.html
564 cd bas
565 mv * ..
566 cd ..
567 rmdir bas
568 \endcode
569
570
571 \section libapi C Headers
572
573 Since fb-doc needs to generate C-like code for the back-end parsers,
574 it can also be useful to create a set of C headers for a library
575 written in FreeBasic. By default the FB types get mangled in to one
576 word (for documentation purposes). Ie a FB parameter <em>byref Nam
577 as const short</em> gets the pseudo C code <em>byref_as_const_short
578 Nam</em>. This mangling can get suppressed by option \em --cstyle
579 and fb-doc emitts real C types. In that case the example gets
580 <em>const short* Nam</em> and this code can be used by a C compiler.
581
582 So when we need C headers for our FB library we just execute
583
584 \code fb-doc --csource --fileoutput "*.bi" \endcode
585
586 in our source folder and get a set of C translations in *.\em h
587 files in the target folder (<em>../doc/c_src</em> by default).
588
589 \note fb-doc doesn't handle initializers. You have to check them
590 maunally.
591
592
593 \section usagepipe Piping
594
595 By default fb-doc reads its input for (one or more) files and sends
596 its output to StdOut. We can switch to StdIn input by option \em
597 --geany and then use the operating system commands to control the
598 data flow in and from fb-doc.
599
600 Ie this is useful when we don't use Geany IDE or when we want to get
601 templates for a complete file or a bunch of files at once. We can
602 pipe the files context to the fb-doc StdIn channel and the fb-doc
603 output to a file.
604
605 To get templates for all constructs in an existing file, first we
606 create a copy the file (example for LINUX OS)
607
608 \code cp filename.bas filename.txt \endcode
609
610 Then we pipe the copy to fb-doc in geany mode (using emitter \em
611 DoxygenTemplates here). The output gets piped to the original file
612 (omit <em>>filename.bas</em> to see the output in the console)
613
614 \code fbdoc --geany doxy < filename.txt > filename.bas \endcode
615
616 Finally we may want to delete the intermediate file
617
618 \code rm filename.txt \endcode
619
620 To insert templates in all files of an existing project we write a
621 batch file (or FB program) that does these three steps for all our
622 source files.
623
624 */
625
626 /** \page pagetables Tables
627 \tableofcontents
628
629 This page contains some information on fb-doc in table format.
630
631 \section sectionoptions Options
632
633 Table of all fb-doc options. An option starts by a minus character
634 followed by a single character (short form) or by two minus
635 characters followed by a word (long form). Both forms have the same
636 meaning.
637
638 Each word in the command line without the leading '-' character gets
639 interpreted as a file name or pattern (ie a string in single or
640 double quotes). The only exeptions are the (may be qouted) strings
641 right behind the \em --emitter or \em --path options, which gets
642 interpreted as a path or emitter name.
643
644 <TABLE>
645
646 <TR><TH> Option </TH>
647 <TH> Parameter </TH>
648 <TH> Description </TH></TR>
649
650 <TR><TD> \em -a or \em --asterix </TD>
651 <TD> none </TD>
652 <TD> emit lines in a multi line comment block with leading '* '
653 characters (gtk-doc style)</TD> </TR>
654
655 <TR><TD> \em -c or \em --cstyle </TD>
656 <TD> none </TD>
657 <TD> emit types in real C syntax (instead of FB styled pseudo C
658 syntax) </TD> </TR>
659
660 <TR><TD> \em -e or \em --emitter </TD>
661 <TD> Emitter name </TD>
662 <TD> Use the specified emitter. Standard emitters are named \em
663 C_Source, \em ListOfFunction, \em GtkDocTemplates and \em
664 DoxygenTemplates. fb-doc will compare the specified name with each
665 emitter name and apply this emitter if there is a match. Comparison
666 is done non-case-sensitve and just the given characters are
667 compared, so ie \em dox matches \em DoxygenTemplates. If no match is
668 found, fb-doc tries to load and use an external emitter module as a
669 dynamic linked library from its EXEPATH. If there is no such modul,
670 the standard emitter is used (each run mode has its own standard
671 emitter). </TD></TR>
672
673 <TR><TD> \em -f or \em --fileoutput </TD>
674 <TD> none </TD>
675 <TD> scan the current folder for file(s) or pattern(s) and
676 create similar C source including comments in the folder
677 <em>../doc/c_src</em></TD>. When no filename or pattern is
678 specified, all *.\em bas and *.\em bi files gets translated. </TR>
679
680 <TR><TD> \em -g or \em --geany </TD>
681 <TD> Emitter name </TD>
682 <TD> read input from StdIn (normaly send in Geany to receive the
683 selected text block, default emitter is GtkDocTemplates) </TD> </TR>
684
685 <TR><TD> \em -h or \em --help </TD>
686 <TD> none </TD>
687 <TD> print the help text and stop </TD> </TR>
688
689 <TR><TD> \em -l or \em --list </TD>
690 <TD> filename or pattern </TD>
691 <TD> scan the current folder for one file, a file pattern or all
692 FbreeBasic source files *.\em bas and *.\em bi and collect the names
693 of all functions. Write them in to the file \em fb-doc.lfn (override
694 existing or create new if not exist). This file is used to create
695 caller and callee graphs with Doxygen back-end. </TD> </TR>
696
697 <TR><TD> \em -p or \em --path </TD>
698 <TD> path name </TD>
699 <TD> specify the folder to start scanning </TD> </TR>
700
701 <TR><TD> \em -r or \em --recursiv </TD>
702 <TD> none </TD>
703 <TD> scan input files in the current folder and all subfolders </TD> </TR>
704
705 <TR><TD> \em -t or \em --tree </TD>
706 <TD> none </TD>
707 <TD> scan the source tree and follow all \#INCLUDE statements </TD> </TR>
708
709 <TR><TD> \em -v or \em --version </TD>
710 <TD> none </TD>
711 <TD> print the version information and stop </TD> </TR>
712
713 </TABLE>
714
715 \note An empty command line makes fb-doc to output the help text
716 (as if option \em --help was given).
717
718 \note In case of interaction between multiple options the latest is
719 the dominant (see \ref tabrunmodi for details).
720
721
722 \section tabemitters Inbuild Emitters
723
724 fb-doc comes with four inbuild emitters to target different goals.
725 Option \em --emitter (\em -e) is used to choose the one in use.
726 (There cannot be more than one emitter in use.)
727
728 Inbuild emitters can be specified by the complete name or just a
729 part of it. fb-doc compares all characters of the (non-quoted) word
730 behind the \em --emitter option against the names of the inbuild
731 emitters (non-case-sensitive), as listed in the following table.
732
733 Beside inbuild emitters also external emitters can be used by
734 specifying the library name after the \em --emitter option (full
735 name including suffix, case sensitive on LINUX). A quoted string
736 gets allways interpreted as a library name. See \ref extend and
737 \ref Options::chooseEmitter() for further information.
738
739 <TABLE>
740
741 <TR><TH> Name </TH>
742 <TH> Prefered Mode </TH>
743 <TH> Function </TH></TR>
744
745 <TR><TD> C_Source </TD> <TD> gtk-doc or Doxy-Filter </TD> <TD> Emit
746 translated FB source in (pseudo) C syntax (default) or real C syntax
747 (option \em --cstyle) </TD></TR>
748
749 <TR><TD> GtkDocTemplates </TD>
750 <TD> Geany </TD>
751 <TD> Generate templates for gtk-doc (default in \em --geany mode).
752 This emitter doesn't support the option \em --tree. </TD></TR>
753
754 <TR><TD> DoxygenTemplates </TD> <TD> Geany </TD> <TD> Generate
755 templates for Doxygen. This emitter doesn't support the option \em
756 --tree. </TD></TR>
757
758 <TR><TD> Callees </TD>
759 <TD> create \em fb-doc.lfn </TD>
760 <TD> Emit all function names to be used in a further run in
761 Doxy-Filter mode (default in \em --list mode) </TD></TR>
762
763 </TABLE>
764
765 \note It's recommended to specify an internal emitter by its
766 (non-quoted) name and external emitter moduls by a quoted
767 string.
768
769
770 \section tabrunmodi Input / Output
771
772 Some options control the execution of fb-doc and the streams of
773 input and output data. The following table shows the relations
774 between working mode and input / output targets:
775
776 <TABLE>
777
778 <TR><TH> Run-Mode </TH>
779 <TH> Option </TH>
780 <TH> Input </TH>
781 <TH> Output </TH>
782 <TH> Default Emitter </TH></TR>
783
784 <TR><TD> Doxy-Filter </TD>
785 <TD> none </TD>
786 <TD> one file </TD>
787 <TD> standard out (StdOut) </TD>
788 <TD> C_Source </TD></TR>
789
790 <TR><TD> gtk-doc </TD>
791 <TD> \em -f or \em --fileoutput </TD>
792 <TD> one file, files matching a pattern or all source files </TD>
793 <TD> *.\em c and *.\em h files </TD>
794 <TD> C_Source </TD></TR>
795
796 <TR><TD> Geany templates </TD>
797 <TD> \em -g or \em --geany </TD>
798 <TD> standard in (StdIn) </TD>
799 <TD> standard out (StdOut) </TD>
800 <TD> GtkDocTemplates </TD></TR>
801
802 <TR><TD> List-Generation </TD>
803 <TD> \em -l or \em --list </TD>
804 <TD> files matching a pattern or all source files </TD>
805 <TD> file \em fb-doc.lfn </TD>
806 <TD> Callees </TD></TR>
807
808 <TR><TD> Help </TD>
809 <TD> \em -h or \em --help </TD>
810 <TD> none </TD>
811 <TD> standard out (StdOut) </TD>
812 <TD> none </TD></TR>
813
814 <TR><TD> Info </TD>
815 <TD> \em -v or \em --version </TD>
816 <TD> none </TD>
817 <TD> standard out (StdOut) </TD>
818 <TD> none </TD></TR>
819
820 </TABLE>
821
822 \note the default mode is the Doxygen filter mode, since Doxygen
823 doesn't allow to send further options (directly).
824
825 \note Input and output channels are fixed to the listed options.
826 But you can apply changes, ie by specifying an other the emitter
827 with \em --emitter option or input more than one file by walking
828 through the source tree with \em --tree option, ...
829
830 \note The modi \em --help (\em -h) and \em --version (\em -v)
831 are not related to any FB source. Instead of using an emitter
832 they create fixed output on standard output channel (StdOut).
833
834 \note When more then one run mode is specified in the command line,
835 the latest is the dominant.
836
837
838 \section tabfilenames File Names
839
840 Any text in the command line not matching an option or its parameter
841 gets interpreted as a file name or file pattern. They get added to a
842 queue and fb-doc executes this queue in the given order. Depending on
843 the file name and the run mode fb-doc operates in different ways:
844
845 <table>
846
847 <TR><TH> Option (run-mode) </TH>
848 <TH> no name </TH>
849 <TH> exact name </TH>
850 <TH> pattern </TH></TR>
851
852 <TR><TD> default </TD>
853 <TD> print help text </TD>
854 <TD> load file, emit output to StdOut </TD>
855 <TD> load all files matching the pattern, emit output to StdOut </TD></TR>
856
857 <TR><TD> -f or --fileoutput </TD> <TD> load all *.\em bas and *.\em
858 bi files, emit output for each file to a *.\em c or *.\em h file
859 </TD>
860 <TD> load this one file, scan the source tree and load each
861 \#INCLUDE file, emit output for each file to a *.\em c or *.\em
862 h file </TD>
863 <TD> load all files matching the pattern, emit output for each file
864 to a *.\em c or *.\em h file </TD></TR>
865
866 <TR><TD> \em -g or \em --geany </TD>
867 <TD> ignored </TD>
868 <TD> ignored </TD>
869 <TD> ignored </TD></TR>
870
871 <TR><TD> \em -l or \em --list </TD> <TD> load all *.\em bas and *.
872 \em bi files, emit output to one file named \em fb-doc.lfn </TD>
873 <TD> load this one file, scan the source tree and load each
874 \#INCLUDE file, emit output to one file named \em fb-doc.lfn</TD>
875 <TD> load all files matching the pattern, emit output to one file
876 named \em fb-doc.lfn</TD></TR>
877
878 </table>
879
880 \note A file name may be prepended by a relative or an absolute path.
881
882 \note File names or paths including a space character have to be
883 enclosed by single or double qoutes.
884
885 \note Multiple file names get separated by a space character or by a
886 ; character.
887
888 \note A file name cannot start with a minus character and cannot
889 include single or double quote characters.
890
891
892 \section tabmangling Type Mangling
893
894 fb-doc mangles the keywords of a FB type declaration in to a single
895 word, separated by an underscore character. The following table
896 contains some examples. This mangling can get suppressed by option
897 \em --cstyle, to get real C types emitted.
898
899 <table>
900
901 <TR><TH> FB source </TH>
902 <TH> default </TH>
903 <TH> \em --cstyle </TH></TR>
904
905 <TR><TD> DIM AS INTEGER Nam</TD>
906 <TD> INTEGER Nam </TD>
907 <TD> int Nam </TD></TR>
908
909 <TR><TD> DIM Nam AS INTEGER</TD>
910 <TD> INTEGER Nam </TD>
911 <TD> int Nam </TD></TR>
912
913 <TR><TD> CONST Nam AS INTEGER</TD>
914 <TD> CONST_INTEGER Nam </TD>
915 <TD> const int Nam </TD></TR>
916
917 <TR><TD> Extern Nam AS INTEGER</TD>
918 <TD> Extern_INTEGER Nam </TD>
919 <TD> extern int Nam </TD></TR>
920
921 <TR><TD> DECLARE PROPERTY CurTok() AS INTEGER PTR </TD>
922 <TD> PROPERTY_AS_INTEGER_PTR CurTok() </TD>
923 <TD> int *CurTok(void) </TD></TR>
924
925 <TR><TD> BYVAL Export_ AS EmitFunc </TD>
926 <TD> BYVAL_AS_EmitFunc Export_ </TD>
927 <TD> EmitFunc *Export_ </TD></TR>
928
929 <TR><TD> byref Z as byte </TD>
930 <TD> byref_as_byte Z </TD>
931 <TD> char *Z </TD></TR>
932
933 <TR><TD> byval Z as byte </TD>
934 <TD> byval_as_byte Z </TD>
935 <TD> char Z </TD></TR>
936
937 </table>
938
939
940 \section tabundocfiles Undocumented files
941
942 The \em src folder in the fb-doc archive contains two more files,
943 which are not included in the files list in this ducumentation.
944 These are files used by Doxygen, check its manual for details:
945
946 <table>
947
948 <TR><TH> Name </TH>
949 <TH> Function </TH></TR>
950
951 <TR><TD> Doxyfile </TD>
952 <TD> A configuration file, controlling the Doxygen operation. </TD></TR>
953
954 <TR><TD> DoxygenLayout.xml </TD>
955 <TD> A configuration file, controlling the index context of these \em html pages. </TD></TR>
956
957 </table>
958
959 */
960
961 /** \page externfiles Files used
962 \tableofcontents
963
964 fb-doc currently uses two external files. It tries to load the
965 context when needed and continues without the context when the files
966 aren't present. fb-doc searches for the files in the EXEPATH (the
967 folder of the fb-doc binary).
968
969 \section filecsrc ../doc/c_src
970
971 This folder gets created by fb-doc to write the file output. It's
972 used to collect the translations from the \em C_source emitter. The
973 back-end read its input from here.
974
975 \section filecallees fb-doc.lfn
976
977 The suffix lfn means list of function names. This file is used in
978 the C_SOURCE emitter to create pseudo function calls in a function
979 body. It gets created by the ListOfFunction emitter when using
980 (option \em --list) and it isn't used in Geany mode (option \em
981 --geany, emitters GtkDocTemplates and DoxygenTemplates).
982
983 Allthough it's usually created by fb-doc, it also can get
984 manipulated by any text editor.
985
986 The file contains the names of all functions in the source code.
987 Member functions of a UDT are listed as they are named in the
988 function body (ie TypeName.FunctionName). The first line is empty.
989 Further lines contain the names, one in each line, including the dot
990 in case of a member function. The lines \b must be separated by a
991 single line feed character (LINUX line end = 'CHR(10)'). So be
992 careful when we edit on DOS / windows (ie use Geany and switch to
993 LF line ends).
994
995 This file is needed when running as a filter for Doxygen to create
996 the caller and callees graphs. Therefor the bodys of the function
997 have to include the function calls. fb-doc checks all words in a
998 function body against the known function names. Any match gets
999 emitted as a pseudo function call (with empty parameter list).
1000
1001 Since in this mode Doxygen serves the file names in any order and
1002 fb-doc gets started new for each file, it doesn't know about a
1003 function declaration from file A when working on file B. Therefor the
1004 function names have to be served from an external source. They get
1005 red from this file at each program start.
1006
1007 The file offers an additional way to control the context of the caller
1008 and callees graphs. Only functions listed in this file gets included
1009 in the C source (and in the graphs).
1010
1011 When this file isn't present fb-doc continues execution without any
1012 message and the function bodys of the pseudo C code are empty. This
1013 means no caller or callees graphs will be created.
1014
1015
1016 \section fileempty empty.txt
1017
1018 This file is used in Geany mode (option \em --geany). When we send an
1019 empty block to fb-doc (place the cursor in an emppty line and call
1020 fb-doc) then a standard text gets emitted to our source file. This
1021 is a documentation block
1022
1023 - for a section, when in gtk-doc mode or
1024 - for a file, when in Doxygen mode.
1025
1026 We can replace these standard blocks by the context of this file.
1027 When fb-doc finds this file in the EXEPATH it emits its context
1028 instead of the standard text to fill an empty line. The file gets
1029 red each time when passing an empty block, so we can edit the file
1030 and use the new context without restarting Geany or fb-doc.
1031
1032 Usually this file contains a comment block with any kind of
1033 documentation. When the file isn't present the standard text of the
1034 emitter gets emited.
1035
1036
1037 \section externemitters External Moduls (*.so / *.dll)
1038
1039 fb-doc can use external emitter modules. These are executable
1040 binaries, compiled and linked as a library for dynamic linkage,
1041 either by using the FreeBasic compiler or any other compiler / linker
1042 combination. These files may have any name and get the system
1043 specific file name extension (= suffix) \em .so on LINUX or \em .dll
1044 on windows.
1045
1046 Such files aren't necessary for basic usage of fb-doc. They are used
1047 for external emitters to extend the fb-doc features and get loaded on
1048 demand (option \em --emitter) at run-time, see \ref extend for
1049 details. So you may have one or more files with one of these
1050 suffixes in your working directory.
1051
1052 */
1053
1054
1055 /** \page examples Examples
1056 \tableofcontents
1057
1058 Here're some examples for the features of fb-doc (using gtk-doc or
1059 Doxygen back-end).
1060
1061
1062 \section exacomments Comments (in general)
1063
1064 \note In these examples the ends of the FreeBasic multi line
1065 comments are fakes, because the straight single quote mark cannot be
1066 used in the source. Instead an acute accent is used. Correct them
1067 when you intend to copy / paste the code.
1068
1069 A line end comment in the FB source like
1070 \code '* a line end comment \endcode
1071
1072 gets emitted as
1073 \code //! a line end comment \endcode
1074
1075 Direct export comments in FB source (each are line end comments) like
1076 \code
1077 '&// a line end comment in C syntax
1078
1079 '&/*
1080 '&Some
1081 '&lines of
1082 '&C comment
1083 '&*/
1084 \endcode
1085
1086 get emitted as
1087 \code
1088 // a line end comment in C syntax
1089
1090 /*
1091 Some
1092 lines of
1093 C comment
1094 */
1095 \endcode
1096
1097 And a multi line comment in FB source like
1098 \code
1099 /'*
1100 Some
1101 lines of
1102 comment `/
1103 \endcode
1104
1105 gets emitted as
1106 \code
1107 /**
1108 Some
1109 lines of
1110 comment */
1111 \endcode
1112
1113 or &mdash; when option \em --asterix is set &mdash; as
1114 \verbatim
1115 /**
1116 * Some
1117 * lines of
1118 * comment */
1119 \endverbatim
1120
1121 Normal FreeBasic comments (without magic character) wont be emitted.
1122 (They're only visible in the FB source, The intermediate format
1123 contains empty line in that case.)
1124 \code
1125 ' a line end comment
1126
1127 /'
1128 A block
1129 of
1130 comment
1131 `/
1132 \endcode
1133
1134
1135 \section exadim Variable Declaration
1136
1137 A varible declaration in a FreeBasic source code line like
1138 \code
1139 DIM VarName AS ZSTRING PTR
1140 \endcode
1141
1142 gets in the intermediate (C-like) format
1143 \code
1144 ZSTRING_PTR VarName;
1145 \endcode
1146
1147 The FB type <em>ZSTRING PTR</em> consists of two words. The C
1148 scanner can not handle it directly. That's why fb-doc mangels the
1149 words in to one word, separeted by an underscore. Now the lexical
1150 scanner of the C tool-chain interprets the single word \em
1151 ZSTRING_PTR as a user defined type (or macro) and generates
1152 documentation like \verbatim ZSTRING_PTR VarName \endverbatim See
1153 \ref tabmangling for more examples.
1154
1155 In this syntax the FB user can identify the type as an FB
1156 declaration and easily understand the documentation. The only
1157 difference is that in the documentation context the type is allways
1158 in front of the name (C style) while FB allows to swap the order
1159 (and in FB parameter lists the name must be in front of the type),
1160
1161 fb-doc can also generate real C types. In this case the above
1162 example gets
1163 \code
1164 char* VarName;
1165 \endcode
1166
1167 and this syntax can be used direrctly by a C compiler (this can be
1168 useful to auto-generate C headers with fb-doc, ie for a library
1169 written in FB that should be used in a C project).
1170
1171
1172 \section exagtkdoc Gtk-doc
1173
1174 \note This example is based on a system wide installation of fb-doc
1175 and a setting as Geany custom command with option \em --geany. (See
1176 \ref installgeany for details.))
1177
1178 This example is about documenting a function and its parameter list.
1179 We load our source code in to Geany IDE, select the function
1180 declaration (the code in the following bix) and send it to the
1181 fb-doc custom command:
1182
1183 \code
1184 FUNCTION goo_axis_new CDECL( _
1185 BYVAL Parent AS GooCanvasItem PTR, _
1186 BYVAL Back AS GooCanvasItem PTR, _
1187 BYVAL Text AS gchar PTR, _
1188 BYVAL Modus AS GooAxisType, _
1189 ...) AS GooAxis PTR
1190 \endcode
1191
1192 fb-doc extracts the names of the function and its parameters,
1193 generates a matching template and returns the customized template
1194 and the original code. The entries for the individual documentation
1195 text are marked with then text \em FIXME:
1196
1197 \code
1198 /'*
1199 goo_axis_new:
1200 @Parent: FIXME
1201 @Back: FIXME
1202 @Text: FIXME
1203 @Modus: FIXME
1204 @...: FIXME
1205
1206 FIXME
1207
1208 Returns: FIXME
1209 `/
1210 FUNCTION goo_axis_new CDECL( _
1211 BYVAL Parent AS GooCanvasItem PTR, _
1212 BYVAL Back AS GooCanvasItem PTR, _
1213 BYVAL Text AS gchar PTR, _
1214 BYVAL Modus AS GooAxisType, _
1215 ...) AS GooAxis PTR
1216 \endcode
1217
1218 Now we complete the documentation comment by filling the entries
1219 marked by the text \em FIXME, and we end-up with something like:
1220
1221 \code
1222 /'*
1223 goo_axis_new:
1224 @Parent: the parent item, or %NULL. If a parent is specified, it
1225 will assume ownership of the item, and the item will
1226 automatically be freed when it is removed from the
1227 parent. Otherwise call g_object_unref() to free it.
1228 @Back: the background box to connect the axis to (a
1229 #GooCanvasRect, #GooCanvasImage, #GooCanvasGroup, ...).
1230 Note: to set the axis position and size, the properties
1231 #GooCanvasItemSimple:x, #GooCanvasItemSimple:y,
1232 #GooCanvasItemSimple:width and
1233 #GooCanvasItemSimple:height will be red (and therefore
1234 must be set in the background box item).
1235 @Text: the label text for the axis
1236 @Modus: the position and type (like %GOO_AXIS_SOUTH or
1237 %GOO_GRIDAXIS_SOUTH, ...)
1238 @...: optional pairs of property names and values, and a
1239 terminating %NULL.
1240
1241 Creates a new axis item.
1242
1243 Returns: (transfer full): a new axis item.
1244 `/
1245 FUNCTION goo_axis_new CDECL( _
1246 BYVAL Parent AS GooCanvasItem PTR, _
1247 BYVAL Back AS GooCanvasItem PTR, _
1248 BYVAL Text AS gchar PTR, _
1249 BYVAL Modus AS GooAxisType, _
1250 ...) AS GooAxis PTR
1251 \endcode
1252
1253 Finally we translate all FB sources (*.\em bas and *.\em bi) to C
1254 source using
1255 \code fbdoc --asterix --fileoutput \endcode
1256
1257 The files gets written to the path <em>../doc/c_src</em> and the
1258 output in the corresponding .\em c file looks like
1259
1260 \verbatim
1261 /**
1262 * goo_axis_new:
1263 * @Parent: the parent item, or %NULL. If a parent is specified, it
1264 * will assume ownership of the item, and the item will
1265 * automatically be freed when it is removed from the
1266 * parent. Otherwise call g_object_unref() to free it.
1267 * @Back: the background box to connect the axis to (a
1268 * #GooCanvasRect, #GooCanvasImage, #GooCanvasGroup, ...).
1269 * Note: to set the axis position and size, the properties
1270 * #GooCanvasItemSimple:x, #GooCanvasItemSimple:y,
1271 * #GooCanvasItemSimple:width and
1272 * #GooCanvasItemSimple:height will be red (and therefore
1273 * must be set in the background box item).
1274 * @Text: the label text for the axis
1275 * @Modus: the position and type (like %GOO_AXIS_SOUTH or
1276 * %GOO_GRIDAXIS_SOUTH, ...)
1277 * @...: optional pairs of property names and values, and a
1278 * terminating %NULL.
1279 *
1280 * Creates a new axis item.
1281 *
1282 * Returns: (transfer full): a new axis item.
1283 * */
1284 FUNCTION_CDECL_AS_GooAxis_PTR goo_axis_new (
1285 BYVAL_AS_GooCanvasItem_PTR Parent,
1286 BYVAL_AS_GooCanvasItem_PTR Back,
1287 BYVAL_AS_gchar_PTR Text,
1288 BYVAL_AS_GooAxisType Modus,
1289 ...) {
1290
1291 };
1292 \endverbatim
1293
1294 This fb-doc C-like output can be used as input for the gtk-doc
1295 tool-chain to generate the desired documentation output. The tools
1296 operate on the files in the <em>../doc/c_src</em> folder.
1297
1298
1299 \section exadoxy Doxygen
1300
1301 \note This example is based on a system wide installation of fb-doc
1302 and a setting as Geany custom command with option <em>--geany
1303 doxy</em>. (See \ref installation for details.))
1304
1305 We load our code in to Geany IDE, select some source like the
1306 following code and send it to the fb-doc custom command:
1307
1308 \verbatim
1309 FUNCTION goo_axis_new CDECL( _
1310 BYVAL Parent AS GooCanvasItem PTR, _
1311 BYVAL Back AS GooCanvasItem PTR, _
1312 BYVAL Text AS gchar PTR, _
1313 BYVAL Modus AS GooAxisType, _
1314 ...) AS GooAxis PTR
1315 \endverbatim
1316
1317 fb-doc extracts the names and returns the customized template,
1318 followed by the original code:
1319
1320 \verbatim
1321 /'* \fn FUNCTION_CDECL_AS_GooAxis_PTR goo_axis_new (BYVAL_AS_GooCanvasItem_PTR Parent, BYVAL_AS_GooCanvasItem_PTR Back, BYVAL_AS_gchar_PTR Text, BYVAL_AS_GooAxisType Modus, ...)
1322 \param Parent FIXME
1323 \param Back FIXME
1324 \param Text FIXME
1325 \param Modus FIXME
1326 \param ... FIXME
1327
1328 \brief FIXME
1329
1330 \returns: FIXME
1331
1332 FIXME
1333
1334 `/
1335 FUNCTION goo_axis_new CDECL( _
1336 BYVAL Parent AS GooCanvasItem PTR, _
1337 BYVAL Back AS GooCanvasItem PTR, _
1338 BYVAL Text AS gchar PTR, _
1339 BYVAL Modus AS GooAxisType, _
1340 ...) AS GooAxis PTR
1341 \endverbatim
1342
1343 The first line is the declaration of our function in C syntax &mdash;
1344 without the character ; at the end and prepended by the keyword \em
1345 \\fn . This line enables Doxygen to read the documentation comment
1346 anywhere in its input, so the documentations comment needs not to be
1347 in front of the matching function. Since we won't move the block
1348 (it's advantageous to place the documentation text near to the source
1349 code) we remove this line and then we complete the documentation
1350 comment by filling the entries marked by the text \em FIXME. We
1351 end-up with something like:
1352
1353 \verbatim
1354 /'*
1355 \param Parent the parent item, or %NULL. If a parent is specified, it
1356 will assume ownership of the item, and the item will
1357 automatically be freed when it is removed from the
1358 parent. Otherwise call g_object_unref() to free it.
1359 \param Back the background box to connect the axis to (a
1360 #GooCanvasRect, #GooCanvasImage, #GooCanvasGroup, ...).
1361 Note: to set the axis position and size, the properties
1362 #GooCanvasItemSimple:x, #GooCanvasItemSimple:y,
1363 #GooCanvasItemSimple:width and
1364 #GooCanvasItemSimple:height will be red (and therefore
1365 must be set in the background box item).
1366 \param Text the label text for the axis
1367 \param Modus the position and type (like %GOO_AXIS_SOUTH or
1368 %GOO_GRIDAXIS_SOUTH, ...)
1369 \param ... optional pairs of property names and values, and a
1370 terminating %NULL.
1371
1372 \brief Creates a new axis item.
1373
1374 \returns: a new axis item.
1375
1376 A detailed desription of the function may follow here ...
1377
1378 `/
1379 FUNCTION goo_axis_new CDECL( _
1380 BYVAL Parent AS GooCanvasItem PTR, _
1381 BYVAL Back AS GooCanvasItem PTR, _
1382 BYVAL Text AS gchar PTR, _
1383 BYVAL Modus AS GooAxisType, _
1384 ...) AS GooAxis PTR
1385
1386 ' ...
1387 END FUNCTION
1388 \endverbatim
1389
1390 Using Doxygen we don't need to generate intermediate C source code
1391 in files. Instead this code gets directly piped by fb-doc acting as
1392 a filter, so we usually don't see it. Being curious we may generate
1393 files by using fb-doc with option \em --fileoutput and see output like
1394
1395 \code
1396 /**
1397 \param Parent the parent item, or %NULL. If a parent is specified, it
1398 will assume ownership of the item, and the item will
1399 automatically be freed when it is removed from the
1400 parent. Otherwise call g_object_unref() to free it.
1401 \param Back the background box to connect the axis to (a
1402 #GooCanvasRect, #GooCanvasImage, #GooCanvasGroup, ...).
1403 Note: to set the axis position and size, the properties
1404 #GooCanvasItemSimple:x, #GooCanvasItemSimple:y,
1405 #GooCanvasItemSimple:width and
1406 #GooCanvasItemSimple:height will be red (and therefore
1407 must be set in the background box item).
1408 \param Text the label text for the axis
1409 \param Modus the position and type (like %GOO_AXIS_SOUTH or
1410 %GOO_GRIDAXIS_SOUTH, ...)
1411 \param ... optional pairs of property names and values, and a
1412 terminating %NULL.
1413
1414 \brief Creates a new axis item.
1415
1416 \returns: a new axis item.
1417
1418 The detailed desription of the function follows here ...
1419
1420 */
1421 FUNCTION_CDECL_AS_GooAxis_PTR goo_axis_new (
1422 BYVAL_AS_GooCanvasItem_PTR Parent,
1423 BYVAL_AS_GooCanvasItem_PTR Back,
1424 BYVAL_AS_gchar_PTR Text,
1425 BYVAL_AS_GooAxisType Modus,
1426 ...) {
1427
1428 };
1429 \endcode
1430
1431 */
1432
1433 /** \page extend Extending fb-doc
1434
1435 Since the fb-doc Parser calls emitter functions via the emitter
1436 interface \ref EmitterIF, it can get extended by new emitters
1437 providing additional features, ie to support further tools (=
1438 back-ends, ie like <em>source navigator</em>). This can either be
1439 done by adding a new emitter to the fb-doc source or by writing an
1440 external emitter modul, that can be loaded at run-time. The first
1441 variant may have the disadvantage that the extension may need
1442 refactoring when fb-doc gets updated. So it's recommended to prefer
1443 external emitters.
1444
1445 The \em src folder of the \em fb-doc archive contains a file \em
1446 Plugin.bas. In this file you find example source code for an
1447 external emitter modul and this further information:
1448
1449 \dontinclude Plugin.bas
1450 \skipline This emitter generates
1451 \until endverbatim
1452
1453 */
1454
1455 /** \page todo Further Development
1456
1457 In combination with Doxygen fb-doc is a powerful documentation
1458 system for FreeBasic source code. The Doxygen support for FreeBasic
1459 is much better than for any other BASIC dialect (ie like VB6). But
1460 there's still some room for optimization, for Doxygen support as
1461 well as for other features, like:
1462
1463 - optimize syntax high-lighting in listings or examples
1464 - additional emitters to support further documentation systems or other tools
1465 - a hash table for callees to speed up the execution
1466 - ...
1467
1468 Feel free to post your ideas, bug reports, wishes or patches, either
1469 to the project page at
1470
1471 - \ProjPage
1472
1473 or by email to
1474
1475 - \Email
1476
1477 */
1478