[glibmm] Date: Document that some methods return *this, and why.

[Murray Cumming <murrayc src gnome org>]

commit 29198769ae1927629186a53642a7de3e13c36c68
Author: Murray Cumming <murrayc murrayc com>
Date:   Mon Mar 21 08:58:51 2011 +0100

    Date: Document that some methods return *this, and why.
    
    * glib/src/date.hg: Thanks to Kjell Ahlstedt:
    http://mail.gnome.org/archives/gtkmm-list/2011-March/msg00049.html

 ChangeLog        |    7 ++++
 glib/src/date.hg |   87 ++++++++++++++++++++++++++++++++++++------------------
 2 files changed, 65 insertions(+), 29 deletions(-)
---
diff --git a/ChangeLog b/ChangeLog
index 43d2943..986966c 100644
--- a/ChangeLog
+++ b/ChangeLog
@@ -1,3 +1,10 @@
+2011-03-21  Murray Cumming  <murrayc murrayc com>
+
+	Date: Document that some methods return *this, and why.
+
+	* glib/src/date.hg: Thanks to Kjell Ahlstedt:
+	http://mail.gnome.org/archives/gtkmm-list/2011-March/msg00049.html
+
 2.27.97:
 
 2011-03-16  Murray Cumming  <murrayc murrayc com>
diff --git a/glib/src/date.hg b/glib/src/date.hg
index e02aa1f..7aefba1 100644
--- a/glib/src/date.hg
+++ b/glib/src/date.hg
@@ -109,19 +109,19 @@ public:
    */
   void clear();
 
-  /** Parses a user-inputted string str, and try to figure out what date it represents, taking the current locale into account. If the string is successfully parsed, the date will be valid after the call. Otherwise, it will be invalid.   
-   * This function is not appropriate for file formats and the like; it isn't very precise, and its exact behavior varies with the locale. It's intended to be a heuristic routine that guesses what the user means by a given string (and it does work pretty well in that capacity).   
+  /** Parses a user-inputted string str, and try to figure out what date it represents, taking the current locale into account. If the string is successfully parsed, the date will be valid after the call. Otherwise, it will be invalid.
+   * This function is not appropriate for file formats and the like; it isn't very precise, and its exact behavior varies with the locale. It's intended to be a heuristic routine that guesses what the user means by a given string (and it does work pretty well in that capacity).
    * @param str String to parse.
    */
   void set_parse (const Glib::ustring& str);
 
 
   _DEPRECATE_IFDEF_START
-  
+
   //Avoid a build problem in the case that time_t is equivalent to guint32 (GTime is also guint32)
   //That would make the set_time() method overload impossible.
   #ifdef GLIBMM_HAVE_C_STD_TIME_T_IS_NOT_INT32
-  /** Sets the value of a date from a GTime (time_t) value. 
+  /** Sets the value of a date from a GTime (time_t) value.
    *
    * @param time GTime value to set.
    *
@@ -133,7 +133,7 @@ public:
   _DEPRECATE_IFDEF_END
 
 
-  /** Sets the value of a date from a <type>time_t</type> value. 
+  /** Sets the value of a date from a <type>time_t</type> value.
    *
    * @param timet time_t value to set
    *
@@ -148,7 +148,7 @@ public:
    * additional precision.
    *
    * @see set_time_current()
-   * 
+   *
    * @param timeval GTimeVal value to set
    *
    * Since: 2.10
@@ -186,41 +186,67 @@ public:
    */
    void set_julian(guint32 julian_day);
 
-  //TODO: Why return Date& (which is always *this) from these methods?
-  //Isn't it enough to also change the current instance?
-  //murrayc
-  
   /** Add a number of days to a Date.
+   * This method returns a reference to the object itself, so you can write code such as:
+   * @code
+   * somedate.add_days(2).add_months(3).add_years(17);
+   * @endcode
+   *
    * @param n_days Days to add.
    * @return Resulting Date
    */
   Date& add_days(int n_days);
 
   /** Subtract n_days to a Date.
+   * This method returns a reference to the object itself, so you can write code such as:
+   * @code
+   * somedate.subtract_days(2).subtract_months(3).subtract_years(17);
+   * @endcode
+   *
    * @param n_days Days to subtract.
    * @return Resulting Date
    */
   Date& subtract_days(int n_days);
 
   /** Add n_months to a Date.
+   * This method returns a reference to the object itself, so you can write code such as:
+   * @code
+   * somedate.add_years(2).add_months(3).add_days(17);
+   * @endcode
+   *
    * @param n_months Months to add.
    * @return Resulting Date
    */
   Date& add_months(int n_months);
 
   /** Subtract n_months to a Date.
+   * This method returns a reference to the object itself, so you can write code such as:
+   * @code
+   * somedate.subtract_years(2).subtract_months(3).subtract_days(17);
+   * @endcode
+   *
    * @param n_months Months to subtract.
    * @return Resulting Date
    */
   Date& subtract_months(int n_months);
 
   /** Add n_days to a Date.
+   * This method returns a reference to the object itself, so you can write code such as:
+   * @code
+   * somedate.add_years(2).add_months(3).add_days(17);
+   * @endcode
+   *
    * @param n_years Years to add.
    * @return Resulting Date
    */
   Date& add_years(int n_years);
 
   /** Subtract n_years to a Date.
+   * This method returns a reference to the object itself, so you can write code such as:
+   * @code
+   * somedate.subtract_years(2).subtract_months(3).subtract_days(17);
+   * @endcode
+   *
    * @param n_years Years to subtract.
    * @return Resulting Date
    */
@@ -238,9 +264,10 @@ public:
    */
   int compare(const Date& rhs) const;
 
-  /** If date is prior to min_date, sets date equal to min_date. 
+  /** If date is prior to min_date, sets date equal to min_date.
    * If date falls after max_date, sets date equal to max_date. All dates must be valid.
-   * See also clamp_min() and clamp_max(). 
+   * See also clamp_min() and clamp_max().
+   * This method returns a reference to the object itself.
    * @param min_date Date minimum value.
    * @param max_date Date maximum value.
    * @return Date in interval.
@@ -249,6 +276,7 @@ public:
 
   /** If date is prior to min_date, sets date equal to min_date.
    * See also clamp(), and clamp_max().
+   * This method returns a reference to the object itself.
    * @param min_date Date minimum value.
    * @return Date in interval.
    */
@@ -256,11 +284,12 @@ public:
 
   /** If date falls after max_date, sets date equal to max_date.
    * See also clamp(), and clamp_min().
+   * This method returns a reference to the object itself.
    * @param max_date Date maximum value.
    * @return Date in interval.
    */
   Date& clamp_max(const Date& max_date);
-  
+
   /** Checks if date is less than or equal to other date, and swap the values if this is not the case.
    * @param other Date ro compare.
    * @return Date.
@@ -273,7 +302,7 @@ public:
   Weekday get_weekday() const;
 
   /** Returns the month of the year. The date must be valid.
-   * @return Month of the year as a Date::Month. 
+   * @return Month of the year as a Date::Month.
    */
   Month        get_month()               const;
 
@@ -287,9 +316,9 @@ public:
    */
   Day          get_day()                 const;
 
-  /** Returns the Julian day or "serial number" of the Date. 
-   * The Julian day is simply the number of days since January 1, Year 1; 
-   * i.e., January 1, Year 1 is Julian day 1; January 2, Year 1 is Julian day 2, etc. 
+  /** Returns the Julian day or "serial number" of the Date.
+   * The Julian day is simply the number of days since January 1, Year 1;
+   * i.e., January 1, Year 1 is Julian day 1; January 2, Year 1 is Julian day 2, etc.
    * The date must be valid.
    * @return Julian day.
    */
@@ -301,14 +330,14 @@ public:
    */
   unsigned int get_day_of_year()         const;
 
-  /** Returns the week of the year, where weeks are understood to start on Monday. 
-   * If the date is before the first Monday of the year, return 0. 
+  /** Returns the week of the year, where weeks are understood to start on Monday.
+   * If the date is before the first Monday of the year, return 0.
    * The date must be valid.
    * @return Week of the year.
    */
   unsigned int get_monday_week_of_year() const;
 
-  /** Returns the week of the year during which this date falls, if weeks are understood to being on Sunday. 
+  /** Returns the week of the year during which this date falls, if weeks are understood to being on Sunday.
    * Can return 0 if the day is before the first Sunday of the year.
    * The date must be valid.
    * @return Week of the year.
@@ -323,9 +352,9 @@ public:
    */
   unsigned int get_iso8601_week_of_year() const;
 
-  /** Returns true if the date is on the first of a month. 
+  /** Returns true if the date is on the first of a month.
    * The date must be valid.
-   * @return true if the date is the first of the month. 
+   * @return true if the date is the first of the month.
    */
   bool         is_first_of_month()       const;
 
@@ -342,14 +371,14 @@ public:
    */
   static guint8 get_days_in_month(Month month, Year year);
 
-  /** Returns the number of weeks in the year, where weeks are taken to start on Monday. Will be 52 or 53. 
+  /** Returns the number of weeks in the year, where weeks are taken to start on Monday. Will be 52 or 53.
    * (Years always have 52 7-day periods, plus 1 or 2 extra days depending on whether it's a leap year. This function is basically telling you how many Mondays are in the year, i.e. there are 53 Mondays if one of the extra days happens to be a Monday.)
    * @param year Year to count weeks in.
    * @return Number of weeks.
    */
   static guint8 get_monday_weeks_in_year(Year year);
 
-  /** Returns the number of weeks in the year, where weeks are taken to start on Sunday. Will be 52 or 53. 
+  /** Returns the number of weeks in the year, where weeks are taken to start on Sunday. Will be 52 or 53.
    * (Years always have 52 7-day periods, plus 1 or 2 extra days depending on whether it's a leap year. This function is basically telling you how many Sundays are in the year, i.e. there are 53 Sundays if one of the extra days happens to be a Sunday.)
    * @param year Year to count weeks in.
    * @return Number of weeks.
@@ -376,7 +405,7 @@ public:
    */
   void to_struct_tm(struct tm& dest) const;
 
-  /** Returns true if the Date represents an existing day. 
+  /** Returns true if the Date represents an existing day.
    * @return true if the date is valid.
    */
   bool valid() const;
@@ -394,21 +423,21 @@ public:
   static bool valid_month(Month month);
 
 
-  /** Returns true if the year is valid. 
+  /** Returns true if the year is valid.
    * Any year greater than 0 is valid, though there is a 16-bit limit to what Date will understand.
    * @param year Year to check.
    * @return true if the year is valid.
    */
   static bool valid_year(Year year);
 
-  /** Returns true if the weekday is valid. 
+  /** Returns true if the weekday is valid.
    * The 7 Date::Weekday enumeration values are the only valid.
    * @param weekday Weekday to check.
    * @return true if the weekday is valid.
    */
   static bool valid_weekday(Weekday weekday);
 
-  /** Returns true if the Julian day is valid. 
+  /** Returns true if the Julian day is valid.
    * Anything greater than zero is basically a valid Julian, though there is a 32-bit limit.
    * @param julian_day Julian day to check.
    * @return true if the Julian day is valid.
@@ -420,7 +449,7 @@ public:
    * @param day Day to check.
    * @param month Month to check.
    * @param year Year to check.
-   * @return true if the date is a valid one. 
+   * @return true if the date is a valid one.
    */
   static bool valid_dmy(Day day, Month month, Year year);
 };