From 250cdd8e7ec6fad1844dfec9e923c21579a64cca Mon Sep 17 00:00:00 2001 From: Jason Harris Date: Thu, 16 Mar 2006 01:02:58 +0000 Subject: [PATCH] Improve DOX svn path=/trunk/KDE/kdeedu/libkdeedu/; revision=519038 --- extdate/extdatetime.h | 61 ++++++++++++++++++++++++++++++--------- extdate/extdatetimeedit.h | 17 +++++------ 2 files changed, 56 insertions(+), 22 deletions(-) diff --git a/extdate/extdatetime.h b/extdate/extdatetime.h index bf3f4ee..4d09ab5 100644 --- a/extdate/extdatetime.h +++ b/extdate/extdatetime.h @@ -5,8 +5,8 @@ Copyright (c) 2004 by Michel Guitel Copyright (c) 2004-2006 by Jason Harris - This code was adapted from the Qt classes QDate and QDateTime, - copyright Trolltech, Inc. andlicensed under the GNU GPL. + Note: This code was adapted from the Qt classes QDate and QDateTime, + copyright Trolltech, Inc. and licensed under the GNU GPL. If there is ever a need for an LGPL version of these classes, they will need to be reimplemented from scratch to avoid violating @@ -52,9 +52,19 @@ extern void test2_unit(int y, int m, int d); *ExtDate encapsulates the calendar date. It is functionally identical *to the Qt class QDate, except that it allows for dates far outside the *range of valid QDates (years 1752-8000). In fact, there is no limit - *to the range of dates posiible, but for practical reasons we limit + *to the range of dates possible, but for practical reasons we limit *the range of allowable years to -50000 to 50000. * + *The date is represented internally as the Julian Day number (stored + *as a long int). We also store the year, month and day values as + *integers. + * + *The class provides functions for converting ExtDates to and from + *QDates, Julian Days, and string expressions. It also provides + *operators for comparing ExtDate objects. ExtDates can be manipulated + *by setting the Julian Day, or the year, month or day values. Years, + *months and days may also be incremented. + * *@author Michael Guitel, Jason Harris */ class KDE_EXPORT ExtDate @@ -78,16 +88,16 @@ class KDE_EXPORT ExtDate *@short Constructor *Create an ExtDate from the specified QDate *@p q The QDate representing the date to be created - *@note Of course, this will not work if you need a date outside the - *valid Qt range (years 1752-8000). + *@note Of course, this constructor cannot be used if you + *need a date outside the valid Qt range (years 1752-8000). */ ExtDate( const QDate &q ) { ExtDate( q.year(), q.month(), q.day() ); } /** *@short Constructor *Create an ExtDate for the specified Julian Day. *@p jd the Julian Day of the date to be created - *@note The Julian Day is a simple count of the number of days - *elapsed since January 1st, in the year -4713. + *@note The Julian Day is a simple count of the number + *of days elapsed since January 1st, in the year -4713. */ ExtDate( long int jd ); @@ -102,16 +112,16 @@ class KDE_EXPORT ExtDate /** *@return true if the ExtDate is a valid date. *@note A date may be invalid if it is a Null date, if - *its year value exceeds the valid range (-50000 to 50000), or - *if its month or day values are out of bounds. + *its year value exceeds the valid range (-50000 to 50000), + *or if its month or day values are out of bounds. */ bool isValid() const; /** *@return the ExtDate, converted to a QDate. *@note If the ExtDate is invalid or falls outside the range - *of valid QDates (years 1752 to 8000), the QDate returned will - *be invalid. + *of valid QDates (years 1752 to 8000), the returned QDate + *will be invalid. */ QDate qdate() const; @@ -427,6 +437,9 @@ private: *is no limit to the range of dates posiible, but for practical reasons we *limit the range of allowable years to -50000 to 50000. * + *Internally, an ExtDateTime is simply an ExtDate paired with a QTime, with + *very little interaction between these two pieces. + * *@author Michael Guitel, Jason Harris */ class KDE_EXPORT ExtDateTime @@ -437,13 +450,13 @@ public: */ ExtDateTime(); /** - *@short Constructor. Sets date according to the argument; + *@short Constructor. Sets the date according to the argument; *the time is set to midnight. *@p d The date to be set */ ExtDateTime( const ExtDate &d ); /** - *@short Constructor. Sets date and time according to the argument; + *@short Constructor. Sets date and time according to the arguments *@p d The date to be set *@p t The time to be set */ @@ -585,11 +598,33 @@ public: */ int secsTo( const ExtDateTime &dt ) const; + /** + *@return true if the two ExtDateTime objects are equal + */ bool operator==( const ExtDateTime &dt ) const; + /** + *@return true if the two ExtDateTime objects are not equal + */ bool operator!=( const ExtDateTime &dt ) const; + /** + *@return true if the left-hand ExtDateTime object is less than + *the right-hand ExtDateTime object. + */ bool operator<( const ExtDateTime &dt ) const; + /** + *@return true if the left-hand ExtDateTime object is less than + *or equal to the right-hand ExtDateTime object. + */ bool operator<=( const ExtDateTime &dt ) const; + /** + *@return true if the left-hand ExtDateTime object is greater than + *the right-hand ExtDateTime object. + */ bool operator>( const ExtDateTime &dt ) const; + /** + *@return true if the left-hand ExtDateTime object is greater than + *or equal to the right-hand ExtDateTime object. + */ bool operator>=( const ExtDateTime &dt ) const; /** diff --git a/extdate/extdatetimeedit.h b/extdate/extdatetimeedit.h index ae257c6..c5a8d4d 100644 --- a/extdate/extdatetimeedit.h +++ b/extdate/extdatetimeedit.h @@ -22,12 +22,12 @@ *@short provides a spinbox widget for entering an extended date. * *The date is shown using a slight modification of the user's - *localized dateFormatShort, with day, month and year fields shown - *with some kind of delimiter ("/", "-", etc). The modification is - *that two-digit years are disallowed, so if the user's - *dateFormatShort uses a two-digit year, this will be changed to - *show all year digits (but only for the purposes of this widget, - *of course). + *localized dateFormatShort, in which the day, month and year fields + *are shown with some kind of delimiter ("/", "-", etc). The + *modification is that two-digit years are disallowed, so if the + *user's dateFormatShort uses a two-digit year, this will be changed + *to show all the year's digits (but only for the purposes of this + *widget, of course). * *The user can choose which field will be modified with the up/down *buttons or arrow keys by clicking on the desired field. The @@ -93,8 +93,7 @@ class ExtDateEdit : public QSpinBox { *and modifies the highlighted value by the given number of steps. *@note Overloaded from QAbstractSpinBox. *@see activeField() - *@p d the date to display (default is current system time) - *@p parent pointer to the parent widget (default: 0) + *@p steps the number to add to the current day/month/year */ void stepBy( int steps ); @@ -120,7 +119,7 @@ class ExtDateEdit : public QSpinBox { *@short set the internal ExtDate value, and display the new *date in the spinbox. * - *@p d reference to the new ExtDate + *@p date reference to the new ExtDate *@see date() */ void setDate( const ExtDate &date ) { m_Date = date; setValue( m_Date.jd() ); } -- 2.47.3