From kde-core-devel  Thu Nov 10 21:41:42 2005
From: Dominik Haumann <dhdev () gmx ! de>
Date: Thu, 10 Nov 2005 21:41:42 +0000
To: kde-core-devel
Subject: Re: Proposed new KDateTime class
Message-Id: <200511102241.42665.dhdev () gmx ! de>
X-MARC-Message: https://marc.info/?l=kde-core-devel&m=113165892618083
MIME-Version: 1
Content-Type: multipart/mixed; boundary="--Boundary-00=_W67cDImNiItpbpW"

--Boundary-00=_W67cDImNiItpbpW
Content-Type: text/plain;
  charset="iso-8859-6"
Content-Transfer-Encoding: 7bit
Content-Disposition: inline

Hi David,

On Tuesday 08 November 2005 23:00, David Jarvie wrote:
> Comments please. (Note that I am going away and won't be able to respond
> for a few days.)

I didn't use the classes, so that's just ideas and questions that arised 
while reading the API.

API inconsistencies:
 - Sometimes it says "timeZone", sometimes "timezone":
   KTimezone, setTimeZone, timeZone. Would be good to go only for one of
   them.
 - There is add{Secs, Days, Months, Years} but only secsTo and daysTo.
   I would actually expect there also is monthsTo and yearsTo.
 - There is dateTime(), but no setDateTime().

How well does it operate with QDateTime. Does something like
KDateTime d = QDateTime::currentDateTime() work (defaulting to local time)?

The API documentation looks pretty good. But what I'm missing (through whole 
KDE mostly) are detailed descriptions in the Qt way. Attached is a changed 
class description. I tried to mention all important methods and added 
several sections. It isn't perfect (maybe even wrong in some points) as you 
can guess ;) so you should improve it, but it's a start.

Also, cross references (@see) are missing.
/** [...]
 *@see daysTo()
/*
int secsTo(...) const;
This could/should be applied to several other methods.

Greetings,
-- 
Dominik

--Boundary-00=_W67cDImNiItpbpW
Content-Type: text/x-c++src;
  charset="iso-8859-6";
  name="kdatetime.dox"
Content-Transfer-Encoding: quoted-printable
Content-Disposition: attachment;
	filename="kdatetime.dox"

/**
=A0* @brief A class representing a date and time with support for time zone=
s.
=A0*
=A0* Topics:
=A0*  - @ref intro
=A0*  - @ref timezones
=A0*  - @ref manipulation
=A0*  - @ref compatibility
=A0*
=A0* @section intro Introduction
=A0*
=A0* The class KDateTime combines a QDate and QTime object (a date/time pai=
r)
=A0* just like QDateTime, but it adds support for an associated time zone. A
=A0* KDateTime object can be created by passing a date and time in its
=A0* constructor. If both the date and time are null, isNull() returns true.
=A0* If the date or the time are valid, isValid() returns true.
=A0*
=A0* @section timezones Time Zones
 *
 * The supported time zones are:
=A0* - a UTC time zone
=A0* - a specified KTimezone
=A0* - a local clock time, using the current system time zone. If the system
=A0* =A0 time zone changes, the UTC time for the instance will change
=A0* =A0 correspondingly.
=A0*
=A0* To set the time zone to a given value use setTimeZone(), to get the
=A0* used time zone call timeZone(). The current time zone can also be
=A0* checked isLocal() and isUTC(), or by using timeSpec(). A KDateTime
=A0* object can be converted to QDateTime by using toUTC(), or to a UNIX
=A0* timestamp since 1st January 1970 by toTime_t().
 *
=A0* @section manipulation Date and Time Manipulation
=A0*
=A0* As already mentioned a valid instance can be created with a given
=A0* constructor. Furthermore, date and time can be set afterwards by calli=
ng
=A0* setDate() and setTime(). date() and time() return the date and time.
=A0*
=A0* With addSecs(), addDays(), addMonths() and addYears() timespans can be
=A0* added. Accordingly, secsTo() and daysTo() returns the timespan to anot=
her
=A0* KDateTime object.
=A0*
=A0* @section compatibility QDateTime Compatibility
=A0*
=A0* Due to the lack of virtual methods in QDateTime, KDateTime is not a
=A0* subclass of QDateTime.
 * @todo maybe other notes here?
=A0*
=A0* @see KTimezone, QDateTime, QDate, QTime
=A0* @author David Jarvie \<software@astrojar.org.uk\>.
=A0* @since 4.0
=A0*/
--Boundary-00=_W67cDImNiItpbpW--