I always have been a fierce sustainer of documented code: code without documentation is not much helpful, because “self-explanatory” code does not really exist; even if you could tell what a single piece of code does, you cannot know for sure how that interacts with the rest of a wider system.
With my recent work on feng I’ve been noticing how important is to write very good documentation of side effects of functions, and even more important is to document eventual mutexes acquired during execution of the function and similar. The feng codebase was barely documented at all when I started working on the project; now it would probably be quite good actually. Ohloh reports 26% of comment-to-code ratio. I still think it’s not high enough.
Unfortunately, I have noticed also that Doxygen seems to have quite some limitations, or I haven’t studied well enough the recent versions. The first problem is that feng is not a standalone project; it uses liberis and netembryo (used to use bufferpool before replacement) and their documentation should probably be tightly coupled. Indeed this has been what really buggered me about bufferpool: part of the logic that feng used to work was embedded in bufferpool, but the documentation wasn’t linked automatically one from the other.
Also, while there is a way to create new commands, it’s not exactly easy, or, last I remember, very flexible. This is quite a problem because it doesn’t help when I have to write to multiple functions things like “Unused parameter for compatibility with GFunc interface” or “Internal function to be called by g_slist_foreach()”, or finally “This function will acquire the Foo::lock mutex”. Consistency needs to be checked manually, and I’m pretty sure right now the documentation is not consistent.
I guess these are some of the reasons why glib and other GNOME-based projects don’t use Doxygen but rather gtk-doc. On the other hand, I sincerely don’t like gtk-doc at all, just like I don’t like the extended formatting allowed by Doxygen: XML-style blocks inside the comments don’t look at their place at all.
I’m sincerely not sure how to solve any of these problems to be honest, maybe some extension to Doxygen, maybe letting Doxygen produce some special XML files instead of directly HTML files, and then hook up some XSLT to that, having some doxygen-style comment like this:
/**
* @brief Do something
*
* @custom acquire-lock Foo::lock
*/
to produce a new special element with name acquire-lock and content Foo::lock, then process that with XSLT to produce a consistent “This function will acquire the lock Foo::lock” would probably be a very welcome addition to me.
I really have to look into this one day; I admit I haven’t studied the internals and advanced supports of Doxygen, especially not in the latest releases. I know it has some kind of XML output but I’m not sure how flexible that is. But not for now, since I already have enough tasks to take care of and stuff to write. One day, maybe.
