2006/9/11, Axel Dörfler <axeld@xxxxxxxxxxxxxxxx>:
Stephan Assmus <superstippi@xxxxxx> wrote: IIRC beyond the reasoning of using DocBook because of its many output formats, we didn't like using doxygen for end user documentation simply because it would blow up the source files that much.
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.
While it's very nice for short internal developer information (as we're using it almost everywhere), putting user docs into the source files only produces clutter. I've also seen only rare cases of people maintaining the information correctly with the code at once. Usually, you'll end up going over it and correct it anyway.
Well, I do think the best place to put the documentation in are the headers. That prevents the 'source' from being cluttered. But I know you have a different opinion and I'd like to leave it at that.
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.
It's also not the right tool in case you have like 10 versions of the same method - just have a look at BRoster::Launch() or BMessenger::SendMessage(). It not only makes it hard to keep those functions up to date, it also makes it harder for the user to retrieve the differences of the methods variants, and which one is the right one for him to use - the BeBook handles this in a much better way.
AFAIK doxygen places overloaded functions near each other. The BeBook might be nicer, but a similar effect can be reached by documenting one member, and have that point to the other members. But you're probably right: this is one of the few places where doxygen would be more work than docbook.
So while the benefits might be tempting, they usually don't turn out as benefits that much. The only thing that I would like to see (that doxygen does IIRC) is to be able to identify missing or wrong function signatures.
Just to sum up what I think it takes to have the API documentation in docbook. - A script that extracts classes, members, functions, data, globals, etc. and verifies whether or not they are in the docbook source - A script that keeps the source up to date (automatically add new members, delete old members, etc) and that warns that things have changed or that things are undocumented. - A script that creates thousands of entities to be able to easily refer to other functions, both in class and in other classes.
We probably also need to use entities and/or scripts to keep the internal structure in a consisten way.
That's what I call clutter. Especially if doxygen does the bulk of things.
Niels
