[ECOS] Generate package documentation a la Doxygen or javadocs?
Sun Nov 9 20:42:00 GMT 2008
>>>>> "Rutger" == Rutger Hofman <firstname.lastname@example.org> writes:
Rutger> I am writing a few eCos packages right now. The
Rutger> documentation for it lives in a doc/ subdir, in DocBook
Rutger> .sgml format. Now, I would really love to maintain the
Rutger> documentation in the header files, a la doxygen
Rutger> (http://www.stack.nl/~dimitri/doxygen/) or javadocs. One
Rutger> is 'forced' to completely document the API, and if the API
Rutger> changes the documentation ought to change 'automatically'
Rutger> with it.
Rutger> Now, I read that the BoostBook project already made a a
Rutger> XSLT to accomplish this tric for their project. However,
Rutger> it seems to be integrated into the Boost environment. I am
Rutger> tempted to explore their distribution and see if it is
Rutger> easy to run the documentation generator stand-alone.
Rutger> Has maybe anyone already done this, or otherwise got any
Rutger> experience with doing the documentation in doxygen/javadoc
I have no personal experience with doing documentation that way, but I
am sceptical about the approach. There is a lot more to proper
documentation than just describing the various functions and their
arguments. Imagine that you were trying to learn how to do network
programming, and your documentation just listed the functions
socket(), connect(), accept() and listen(), with their arguments and
maybe a few extra sentences for each function. The chances of
producing a working application would be slim. Instead what is
minimally needed is an overview, some example code, and pointers at
more complete sources of information - as well as the basic info on
Now, I suspect doxygen and its ilk could be used to write proper full
documentation rather than just skeletons, if used correctly. However,
if you are going to the effort of writing full documentation then, in
my opinion, you are better off using a file format designed for the
job rather than try to squeeze it into a C header file.
On the other hand, having some documentation is (usually) better than
having no documentation at all.
Rutger> As far as licensing is concerned (an eternal issue :-( ),
Rutger> my guess is that in the most restrictive case, I can live
Rutger> with privately generating the DocBook docs from the
Rutger> doxygen-annotated header files, and just publish the
Rutger> generated DocBook docs.
You would have a header file containing both code, licensed under
GPL+exception, and documentation, licensed under Open Publication
License. Clearly there are licensing complications here. I suspect
these have been addressed in other projects, but I do not know any
Bart Veer eCos Configuration Architect
eCosCentric Limited The eCos experts http://www.ecoscentric.com/
Barnwell House, Barnwell Drive, Cambridge, UK. Tel: +44 1223 245571
Registered in England and Wales: Reg No 4422071.
Before posting, please read the FAQ: http://ecos.sourceware.org/fom/ecos
and search the list archive: http://ecos.sourceware.org/ml/ecos-discuss
More information about the Ecos-discuss