Timezone classes

[Adriaan de Groot]

On Thursday 15 September 2005 19:50, David Jarvie wrote:
> Although on the face of it the classes are well commented, in practice when
> one isn't familiar with them, it is difficult to work out what is the exact
> function and relationship of the different classes - I only started to get
> a grasp on it by studying the source code in some detail. Fuller class
> descriptions, and a better overview description, would be extremely useful.
> I could write something once the points below are addressed.

This comes right back to recent discussions about apidox on -core-devel. On 
the one hand, we have fairly good micro-level documentation (individual 
methods) but not much in the way over overviews and examples. In the 
timezones case we're missing a complete example, and we're missing an 
overview of what the classes _as a whole_ are for and how to use them.

The way to deal with this is to write such an overview; it can go in any of 
the relevant header files, and you do something like this:

/** @defgroup timezones

    This is a long explanation of what the timezones classes do 
    and how to handle them. It also has an example, which lives 
    in kdecore/examples/ and which we include using a hint from 
    Brad Hards as follows

    @example timezones.cpp

*/

Next up, add the following to the _class_ documentation for those classes that 
are relevant in the timezones group (there's four I can think of):

    @ingroup timezones

There! That's a start at least to grouping the classes and providing an 
overview.

-- 
These are your friends - Adem
    GPG: FEA2 A3FE Adriaan de Groot
-------------- next part --------------
A non-text attachment was scrubbed...
Name: not available
Type: application/pgp-signature
Size: 187 bytes
Desc: not available
URL: <http://mail.kde.org/pipermail/kde-core-devel/attachments/20050915/8fb7329e/attachment.sig>