[Telepathy] Proposal for changes on tp-qt4

[Simon McVittie]

On Wed, 10 Dec 2008 at 12:37:38 +0000, Andre Moreira Magalhaes wrote:
> - Move all client code from TelepathyQt4 to TelepathyQt4/Client, this 
> includes moving all cli-*.* files to the Client subdir and renaming 
> them, removing the cli- prefix.

I agree, but this is a disruptive change, so we should do it when there are
fewer outstanding branches (in particular, Olli's "handles" branch
and my "cm" branch should go in first).

Olli wanted to reserve Client/ for the stub headers and put all real
code in some other subdirectory; I'm not clear why this is. Olli, can you
explain?

> - In the code generation process we are creating source files in a 
> directory called TelepathyQt4/_gen that will be installed. As these 
> files may and probably will be used by applications, I suggest not 
> putting this files in the _gen dir, instead we should put them in the 
> same dir as the helper classes but with a different nomenclature. For 
> example the generated files for connection-manager.xml would go to 
> TelepathyQt4/Client/connection-manager-interface.* not conflicting with 
> the helper class called TelepathyQt4/Client/connection-manager-*. So all 
> generated files would have a suffix -interface.*.

The reason the _gen directory has such an ugly name is to remind library
users that they should never be #include'd directly. I don't consider the
presence and exact naming of these header files to be API; consider them
to be an implementation detail of the code generation process.

In telepathy-glib the headers in _gen are not even self-contained - you
have to #include some more stuff to make them work. The non-generated
headers like <telepathy-glib/channel.h> take care of doing that, so
these are the only ones that library users should #include.

(Is it conventional in Qt to consider the "lower-case" headers not to be
part of the API either?)

> - As the generated files will also be exported I suggest creating header 
> files for them the same way we do for the helper classes. Example: 
> TelepathyQt4/Client/connection-manager-interface.h would have a 
> corresponding TelepathyQt4/Client/ConnectionManagerInterface.

We could do that, but IMO
<TelepathyQt4/Client/ConnectionManagerInterface> should #include
<TelepathyQt4/cli-connection-manager.h> (or whatever we rename it to) rather
than directly including the generated header; the generated headers
aren't guaranteed to be self-contained.

    Simon