I develop an open-source Objective-C framework, and I use Doxygen to generate the documentation (http://dysart.cs.byu.edu/CHDataStructures). Overall, Doxygen does a nice job, but I have a perennial annoyance that I can't figure out for the life of me.
I use the \name command and Member Groups to group methods by task (these Apple docs show what I'm going for) to make "discovering" the API easier. However, the problem I face is that although methods show in their groups for the class where they are declared, they lose their group association in any subclass where they are inherited/overriden (or, if a protocol, any class where they are implemented) although the member documentation itself is correctly copied (per my configuration). This is odd, to say the least, and problematic in that when I add more methods to an existing group, they don't appear to be associated with each other. For example:
- CHQueue protocol
- CHAbstractListCollection class ("abstract" parent of CHListQueue)
- CHListQueue class (concrete, implements CHQueue)
The CHQueue protocol (like a Java interface) defines queue-related methods and groups them in task categories. On that page, the methods all appear in groups, with the intentional exception of initialization methods. On the CHListQueue class page, the -removeFirstObject is no longer part of the "Removing Objects" group, but appears lumped at the top. (This method has a one line implementation in CHListQueue, but no documentation at that point in the code — the docs are inherited from the CHQueue declaration of the method.)
As another example only involving classes:
- CHLockableDictionary class
- CHOrderedDictionary class (subclass of CHLockableDictionary)
On the child class page, every parent class method that is overridden in the child is lumped at the top.
None of the options I've toyed with in my Doxyfile have been able to correct this strangeness. Worse, I can't find any way to turn off the Member Groups functionality. I'd rather keep the groupings in if Doxygen can do it correctly (or be patched to fix this) but it really detracts from the readability of my API docs. Has anyone else experienced this? Does it happen in languages other than Objective-C? Any tips or tricks to work around it? Time to file another bug?