[ECOS] Generate package documentation a la Doxygen or javadocs?

Bart Veer bartv@ecoscentric.com
Sun Nov 9 20:42:00 GMT 2008


>>>>> "Rutger" == Rutger Hofman <rutger@cs.vu.nl> 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
    Rutger> style?

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
each function.

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
details.

Bart

-- 
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 mailing list