20 Sep
2007
20 Sep
'07
11:51 a.m.
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