| Re: [AD] Proposed changes for Allegro 5 (6?) |
[ Thread Index |
Date Index
| More lists.liballeg.org/allegro-developers Archives
]
Sven Sandberg wrote:
Stepan Roh wrote:
But in-source documentation is good thing.
There are some problems with it too:
- Is it possible to make sections be structured another way than the
source files?
Yes. Use \insection (not portable to JavaDoc).
- Some functions are defined in different files depending on which
platform they are on, so there's no unique natural place to put the
documentation on.
You can document it in some include file. As long as there's a prototype to
it, then Doxygen will find it. Or even better, have al_doxygen.h file, which
has all the docs to those functions, but only gets included #ifdef DOXYGEN
(defined by Doxygen parser).
- allegro._tx contains several generic sections that discuss
programming principles (e.g. "Bitmap objects"), or non-api stuff (e.g.
"Makefile targets"), that would not fit in naturally in any source file.
You can include other files. For example, AllegroGL includes 'mainfile.foo'
(or something like that), which documents installation procedure and some
other basic stuff. The .txt files can be generated from there, or inversely,
this file can be generated by makedoc.
- allegro._tx is not the only file generated by makedoc: there are
totally 8 files mathching allegro/docs/src/*._tx. So we need something
to compile help that does not come from a source file anyway.
See above.
--
- Robert J Ohannessian
"Microsoft code is probably O(n^20)" (my CS prof)
http://pages.infinit.net/voidstar/