[prev in list] [next in list] [prev in thread] [next in thread] 

List:       kde-core-devel
Subject:    Re: Timezone classes
From:       Adriaan de Groot <groot () kde ! org>
Date:       2005-09-15 20:34:28
Message-ID: 200509152234.29149.groot () kde ! org
[Download RAW message or body]


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

[Attachment #3 (application/pgp-signature)]

[prev in list] [next in list] [prev in thread] [next in thread]