Bug 41624

Hereby presented, the full list of doxygen categories ("Modules" in the default generated HTML) in current tp-qt4 git master, annotated with my observations/suggestions:

> Common debug support

Makes sense

> Client-side proxies
>   Generic D-Bus proxies

OK

>   Account proxies

Otherwise OK, but contains Tp::ContactMessenger ??

>   Account manager proxies

OK, but does it need to be a separate category from Account?

>   Channel proxies

Tons of classes. Should be divided to a few subcategories.

>   ChannelDispatcher proxies
>   ChannelDispatchOperation proxies
>   ChannelRequest proxies

OK, but too small and infrequently used to warrant being separate categories. Let's combine them?

>   Client proxies

Contains all the AbstractClient* hierarchy, which are not proxies at all, but more like adaptors / service implementation baseclasses.

>   Connection manager proxies

OK, though protocol info is mostly often accessed through an account nowadays.

>   Connection proxies

Mish mash of *all*, including the actual Connection stuff but also everything Contact related, and capabilities. Even Contact::InfoFields! Not cool at all.

>   Media session handler proxies
>   Media stream handler proxies
>   Telepathy Properties proxy

All three just a single interface which ~nobody uses, the last one even having been deprecated for ages.

> Wrapper classes

A billion unrelated classes, should be documented in the module / category where they're used.

> Utililty classes

Typo, and totally a dumping ground for misc which nobody is going to find from there. Examples:
 - all Filter stuff
 - Factories
 - Feature stuff and ReadinessHelper (which are legitimately misc utilities, granted, but again not at all related with the others currently in this cat)
 - KeyFile, ManagerFile and Profile (also misc utilities but then again also rather tightly related to CM / Acc)
 - Generic PendingOps (misc utils, but ones which we could easily make a separate category of, and then document the general async op pattern and the need for it there)
 - RefCounted and SharedPtr: yeah, but where is Object then? Separate cat for those?
 - Simple*Observer: WTF do they have to do with the rest?!?

> functions

Umm...? Additionally, no contents, just the copyright header. I wonder where this comes from. Probably:

../TelepathyQt4/utils.cpp: * \defgroup utility functions

> Types and constants
>   Utility string constants
>   Flag type constants
>   Enumerated type constants
>   Interface string constants
>   Error string constants
>   Structure types
>   List types
>   Mapping types

Contain exactly what they're supposed to, but like the general trend seems to be, really give the impression that tp-qt4 is all about the generated stuff and tiny bits of directly related higher-level to bring it all together. Which obviously couldn't be farther from the truth nowadays, thankfully. I guess we just stopped thinking about the documentation structure shortly after adding those primitive bits.

Additionally, there are lots of things not in any category. Such as ClientRegistrar, which declares it's in category serverclient (making more sense than the AbstractClient* things in clientclient although they're definitely not client-side bits D-Bus wise). The only problem is that this category doesn't exist (not defined and described anywhere), so it's missing from the outline as well.

I put the StreamTubeClient and StreamTubeServer classes in ClientRegistrar's category too though, pending actually describing the category (when this bug is fixed). Because even if the category is not visible at the moment, it just makes more sense than dumping them in with SharedPtr and KeyFile like the somewhat analogous Simple*Observer classes have been.

Options here: fix all of this, so that people can actually use the Modules doxygen page to get an intuitive outline of what the library has to offer. Or admit that we aren't capable of that and remove the currently misleading Modules page completely. This would make magically knowing the name of the class, and/or following links, the only choices to find the API you need. So I'd rather go with the first if there is ever time to do that...