OK, right, thanks for the explanations about the goal of this week-end, I didn't understand that at first. I looked to me like some sort of "rush" to commit a new documentation system until Monday.
About the current documentation system, there's 3 points :
- 1 - The input format. I'm OK with you about the "non standard wiki" style, but let's be honest : we use very few features, mostly bold (**), mono font (##) and code (%%). I doesn't looks like something horribly complex to parse, is it ? And about the 40 chars/line limit, I'm not sure, but I think you're talking about 80 chars/line one, and it's only a matter of header source "indentation", not a limit of the format/script.
- 2 - The output format. Again, the current script was a one shot try. I quickly wrote this, I was pleased with the current ouput and that's it. I can update it, we can rewrite it to generate whatever is needed (and even Doxygen format, why not), it's only a matter of user request. We can even rewrite it in pure C or even ASM, I doesn't care
In facts, I can't remember of any user request about the documentation so far ... that's probably why the output never changed. That doesn't mean the output can't change or that I don't want it to change !
About Doxygen, I'll try to keep my comment simple: The ouput looks horribly complex to me. The information is spread over many pages, there's a bunch of "tabs" on top, with no visible logic, I must browse files to browse functions ... The general workflow is Doxygen-typic: scrambled. Please, do not misinterpret my message, I don't say the Doxygen output is completely unusable, but it adds nothing to our current antic documentation (even if it's more pretty and light, I admit), I would even say it removes features. And then comes the input syntax: it's rubbish. Really. "code/encode" ? "/*}" ? "/*!<" ? ... and a bunch of HTML tags in the middle. Tasty
Even Javadoc is better on this point ...
I've wrote enough comments with this stupid syntax to know that I don't want to write more. So.
To make it simple, I think the important things are: our
current header doc format. it's simple, It works, so there's no point to fix it, and the
ouput should be crystal clear to the standard-newbie-user.
Until we don't touch to these two points, we can change everything to make the ouput better, more easy to browse, make the tweaking easy, the generation more simple, ...
The first step would simply be to collect user needs. How do we currently use the doc ? What can't we do with this doc ? What can be interesting ?
Please, remember that all this is just my opinion. But spending hours and hours, with many people, to switch by hand to Doxygen doesn't look like a good idea to me. There's so much other things to do in the project !