[Paparazzi-devel] Re: Improving documentation

[Serge Le Huitouze]

Christophe De Wagter wrote:

> Just another (maybe weird) perspective:
>
> The documentation (...) It is quite hard to choose which
> folders to include in doxygen (...)
>

This is certainly not a weird perspective, rather a non dispensable
one!

> "In a project where fast evolution in code exists, the safest
> way to get code and documentation in sync is when they are
> written next to each other in the same file."

This approach is usually called "literate programming" and is quite
appealing, though, probably, not everyone is willing to embark on
such an ambitious approach.
That what I was willing to do with the ocaml code.
But I quickly ran into some problems:
 - the literate programming tool I found (ocamlweb) needs LaTeX to
    run, which, as you may know, is a big bunch of packages, so much
    so that I was not able to install it on my VirtualBox... Trying
    a lighter "distribution" failed to provide me with the necessary
    tools
 - IIUC, some ocaml code (similar to what you have noticed in the
    C code) is not used in all configurations, or is plain obsolete.
    And, IIUC, that's not only entire directories, but sometimes
    scattered files. But I didn't spend much time on this yet, and
    maybe IDUC ;-)


Concerning the second aspect, it seems that an automated approach
starting from the makefiles could help (of course, original contributors
of various files are welcome to help, too! ;-).
I haven't looked into it, but maybe the output of "make --dry-run" would
be exploitable...


> Could we link a doxygen manual to the wiki? (with color coded pages for
> tiny/booz/lisa/common/gcs/etc...).

Colors might seem a good clue, but how will we proceed with pieces of code
that are used in more than one configuration? Rainbow-like pages? ;-)

> Making this will (likely) raise questions
> as how to best organize code (tiny/lisa/booz) and how to know for instance
> which module can run on which platform....

This is obviously linked to my previous point, and an adequate reorganization
should virtually make these "rainbow-like" situations disappear.


Concerning the literate programming approach, does someone know/use such
systems for OCaml and/or C or have some suggestion on the most appropriate
system?
Ideally, a litProg/documentation system should be able to handle all
the languages used in the project (this probably includes makefiles...),
but I'm not sure such a beast exists, and, in case it does, I'm not sure it'd
be practical...


My two cents (though rather handwavy)...

--Serge