ea6578d19b
* NEW: Scripts to generate Gambas documentation files from C/C++ sources git-svn-id: svn://localhost/gambas/trunk@6712 867c0c6c-44f3-4631-809d-bfa615b0a4ec
113 lines
4 KiB
Text
113 lines
4 KiB
Text
About c2help
|
|
------------
|
|
|
|
c2help is used to extract Gambas documentation from C/C++ source files and
|
|
create .help files for a component from them.
|
|
|
|
Project compass
|
|
---------------
|
|
|
|
./extract.awk -- Extract help comments
|
|
./xlate.sh -- Translate C/C++ function names to Gambas symbol names
|
|
./prefix.awk -- Prefix symbol names with the classes they belong to
|
|
./mkhelp.gbs3 -- Create a .help file from the (properly formatted) input
|
|
|
|
./c2help.sh -- Executes the above programs in the correct order to create
|
|
the .help in a number of C/C++ sources.
|
|
|
|
... and why?
|
|
------------
|
|
|
|
Components written in Gambas can already be documented in-code. This docu-
|
|
mentation is then stored inside their .info files. With a similar result
|
|
provided by c2help for C/C++ components, we can document all[*] Gambas in
|
|
its source files (at least my components will be) which makes it, IMHO,
|
|
easier to keep the documentation up-to-date. Also the help could be
|
|
displayed locally by the IDE or remotely once these .help files are imported
|
|
to the gambaswiki.org site.
|
|
|
|
Also, documentation can be bound to a specific source code version, so that
|
|
you get docs for the version of Gambas you are running, not only for the
|
|
development branch.
|
|
|
|
[*] I'm not sure about intrinsic functions, though. Should be feasible,
|
|
looking at gbx_class_info.c...
|
|
|
|
Great! How do I prepare my component?
|
|
-------------------------------------
|
|
|
|
The No 0 rule is to BE CAREFUL! There are quite some rules to remember:
|
|
|
|
1. Documentation syntax.
|
|
|
|
You may write a Gambas documentation comment like
|
|
|
|
/**G
|
|
* Here goes the documentation.
|
|
**/
|
|
BEGIN_METHOD_VOID(ClassName_MethodName)
|
|
/* ... */
|
|
END_METHOD
|
|
|
|
or alternatively
|
|
|
|
/**G Class Symbol
|
|
* Documenting Class.Symbol
|
|
**/
|
|
|
|
Instead of the **/ at the end, you may also write */. Cool, huh?
|
|
|
|
The difference between both notations is that the first must immediately
|
|
precede a BEGIN_{PROPERTY,METHOD,METHOD_VOID) line that defines the symbol
|
|
to which the documentation refers. The second syntax documents the indicated
|
|
symbol -- no matter where the comment is.
|
|
|
|
This is intended to document GB_CONSTANTs or GB_PROPERTY_SELFs which don't
|
|
have a BEGIN_* line. It can neverthelss be used for any other symbol but
|
|
NEVER intermix both syntaxes on a single symbol.
|
|
|
|
The ClassName_MethodName part I call "(implementation) function name". The
|
|
particular format shown is not mandatory. The scripts take the function name
|
|
and look up the corresponding symbol in your GB_DESC[].
|
|
|
|
2. Strict regular expressions.
|
|
|
|
The regular expressions used to filter these comments are somewhat strict.
|
|
You have to pass the spaces exactly as indicated in the line where you
|
|
comment text starts, i.e. <space>*<space>text. Also note that Class and
|
|
Symbol in the second syntax are case sensitive!
|
|
|
|
3. Strict structure.
|
|
|
|
Really. The next empty-or-not line after a syntax-1 help block is taken as
|
|
the symbol definition line. If it's not, you get a wrong symbol name.
|
|
|
|
DON'T try to confuse the parsers by not giving information it needs where
|
|
it expects it.
|
|
|
|
4. Synonyms.
|
|
|
|
The first match for a function name lookup in a GB_DESC[] is taken as the
|
|
"primary" implementation of that symbol. That means the help comment will
|
|
be attched to that symbol. All other symbols which call the same function
|
|
are considered synonyms and are *automatically* documented with the default
|
|
sentence: "This is a synonym for <primary-symbol>". DO NOT document them
|
|
separately using a syntax-2 help block!
|
|
|
|
5. Don't reuse method and property implementations (except for synonyms).
|
|
|
|
As the implementation function name is searched in the GB_DESC[]s in your
|
|
source file, you may not put the same function into different classes -- or
|
|
the parser may get confused.
|
|
|
|
Umm... I need an example
|
|
------------------------
|
|
|
|
gb.openssl and gb.data are partially documented that way. Digest.Hash() and
|
|
Digest._call() in gb.openssl show how to deal with synonyms. There the entry
|
|
for Hash precedes the entry for _call, thus Hash is the primary symbol and
|
|
_call a synonym.
|
|
|
|
To see a sample .help file (on stdout), you can do at the source tree root:
|
|
|
|
$ c2help/c2help.sh gb.openssl
|