[Bug 41624] New: Our doxygen categories vary between making a little sense and none at all

[bugzilla-daemon at freedesktop.org]

https://bugs.freedesktop.org/show_bug.cgi?id=41624

           Summary: Our doxygen categories vary between making a little
                    sense and none at all
           Product: Telepathy
           Version: git master
          Platform: Other
        OS/Version: All
            Status: NEW
          Severity: minor
          Priority: low
         Component: tp-qt4
        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
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...

-- 
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.