2006/9/11, Axel Dörfler <axeld@xxxxxxxxxxxxxxxx>:
> That blowing up is relative. Yes, there are probably sections that > require a lot of documentation, such as overview pages and class > descriptions, but most methods will have a simple documentation. And > there's always the possibility of separating the documentation into a > special file, as done with the midi2 kit.
Can doxygen parse the sources and compare that to external sources/ headers? If not, there is little value in using it IMO.
I'm not sure I understand what you're aiming at. I meant that Doxygen "allows" to put documentation in external files. It acts like a fancy formatter then, yes. But that's still valuable because it acts like a validator (to check whether the member exists), and the syntax is ridiculously easy. Plus, it formats the documentation in a uniform way, something that requires more manual work in docbook.
> I'll also question your idea of 'clutter'. Yes, there is data in > those > files that aren't used for any practical purpose in compiling or > developing the code. At the other hand, it doesn't influence you very > much either. All the editors mark comments in a different way than > code, and I bet there is a vim wizard that has written something to > let vim hide Doxygen comment.
If you hide them, there is little point in having them at all. It's much more helpful for development to document the internal usage and peculiarities of a function than to put end user documentation into it. Everything that makes code hard to read, understand or navigate is clutter IMO. And end user documentation adds to all of those things.
Yes, end-"developer" documentation tends to do that. That's because there is a better place than the source, namely the headers. It requires little manual magic, and the documentation is directly at the place where the API is defined. I actually feel an urge to open that discussion as well, but I won't. Let's first look at what we want for developer documentation.
Isn't that just one script?
Think UNIX, small tools that chain together :-) You know what I mean though. It will complicate the build process. I'm not a fan of magic. Magic usually puts constraints on the flexibility of the technology.
> That's what I call clutter. Especially if doxygen does the bulk of > things.
If it can be used to validate (external) documentation by utilizing sources/headers that would certainly be nice. I didn't like the (few) doxygen docs I've seen so far, but they could probably be improved, too. Last time I looked, doxygen's XML output was pretty poor, though.
Could you name your main problems with doxygen documentation, and I can see whether they can be 'solved'. I read somewhere that Doxygen's XML output has improved a lot, in an e-mail from the developer (Dimitri van Heesch), and that it was stable. I don't really know what good XML means though.
Writing a script that parses XML files to match (and create) Docbook sources sounds similar in difficulty as hacking Doxygen to produce proper Docbook output. But since we have more possibilities with Docbook regarding things like grouping functions logically, I'd prefer to go that way.
Okay, let me put it this way. Instead of discussing the technical possibilities, let's first discuss what you/we want the developer documentation to look like, then we can select the tools to do that.
Niels
