[Bug 41624] New: Our doxygen categories vary between making a little sense and none at all
bugzilla-daemon at freedesktop.org
bugzilla-daemon at freedesktop.org
Sun Oct 9 10:33:32 PDT 2011
Summary: Our doxygen categories vary between making a little
sense and none at all
Version: git master
AssignedTo: telepathy-bugs at lists.freedesktop.org
ReportedBy: ollisal at gmail.com
QAContact: telepathy-bugs at lists.freedesktop.org
CC: andrunko at gmail.com
Hereby presented, the full list of doxygen categories ("Modules" in the default
generated HTML) in current tp-qt4 git master, annotated with my
> Common debug support
> Client-side proxies
> Generic D-Bus proxies
> 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
- all Filter stuff
- 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
- Simple*Observer: WTF do they have to do with the rest?!?
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...
Configure bugmail: https://bugs.freedesktop.org/userprefs.cgi?tab=email
------- You are receiving this mail because: -------
You are the QA contact for the bug.
You are the assignee for the bug.
More information about the telepathy-bugs