[ros-dev] Documentation

[Timo Kreuzer]

My thoughts about documentation:

1. Documenting windows functionality and technical stuff
Andrew Greenwood's documentation is wiki based. And I think that isn't a 
bad idea. (I already thought about creating a small wiki like that 
myself) It provides all means of formatting needed, can be viewed by 
everyone using a webbrowser, you can add links, non-devs could add their 
own findings and we already have a wiki in place. Maybe we should add a 
tech-wiki or something where this stuff could go.
It wouldn't be in our source tree, but I don't think that is really 
needed. IMHO it's way better than a bunch of different format text files.

2. Source code documentation
We currently have a very outdated version of doxygen (both doxygen 
itself and the processed source are really outdated). I currently use 
either koders or krugle to search our code. But both also use quite 
outdated sources (around 0.3.0). So we should think about updating our 
doxygen and probably keeping it at a quite up to date state (only a few 
days old if possible).
Some time ago I had begun to create my own documentation system, but it 
turns out it would be a huge bunch of work to get all the features in 
that doxygen already provides. I only think that doxygen output doesn't 
look that good. So I thought about creating a program that could parse 
doxygen's XML output and create something more MSDN alike.
We should also start to think about a consistent way to write code 
documentation. It's done in several different ways. Ok, we need to stick 
to wine documentation for their code. But we should have a consistent 
style for our own code, like always using @param, @return, etc.

3. Program documentation
Docbook depends on cygwin and for chm's also on ms html help workshop. 
To automatically build the chm's we would need a win32/mingw port of the 
needed tools (sed, xsltproc,...) and we would need an open source chm 
compiler. There's an SoC project from wine: 
http://wiki.winehq.org/SummerOfCode, looks like it was just finished: 
http://www.nabble.com/-1-3--whhc---add-chm-compiler-t4361318.html
We could also simply stick to .hhp / .html files.

Timo