X-Git-Url: http://review.tizen.org/git/?a=blobdiff_plain;f=inc%2FFLclGregorianCalendar.h;h=a249a4dada43bf65e2b69b6268f15a2022b17d38;hb=9b44315473e675bcd332e2f56fac1ce00f87a8a6;hp=54c2e8782536e921869cab9749380cdec71d3e58;hpb=d33cc2e9f30697fc25b132353669ecf252a2ce9e;p=platform%2Fframework%2Fnative%2Fappfw.git
diff --git a/inc/FLclGregorianCalendar.h b/inc/FLclGregorianCalendar.h
index 54c2e87..a249a4d 100644
--- a/inc/FLclGregorianCalendar.h
+++ b/inc/FLclGregorianCalendar.h
@@ -1,5 +1,4 @@
//
-// Open Service Platform
// Copyright (c) 2012 Samsung Electronics Co., Ltd.
//
// Licensed under the Apache License, Version 2.0 (the License);
@@ -35,11 +34,12 @@ namespace Tizen { namespace Locales
/**
* @class GregorianCalendar
- * @brief This class is a concrete subclass of calendar and provides the Gregorian calendar that is the most commonly used standard calendar.
+ * @brief This class is a concrete subclass of calendar and provides the Gregorian calendar that is the most commonly used
+ * standard calendar.
*
* @since 2.0
*
- * @final This class is not intended for extension.
+ * @final This class is not intended for extension.
*
* The %GregorianCalendar class is a concrete subclass of calendar and provides the Gregorian calendar that is the most commonly used standard calendar.
*
@@ -85,11 +85,10 @@ class _OSP_EXPORT_ GregorianCalendar
public:
/**
* This is the default constructor for this class. @n
- * The object is not fully constructed after this constructor is called. For full construction, the Construct() method must be called right after calling this constructor.
+ * The object is not fully constructed after this constructor is called. For full construction, the Construct() method must
+ * be called right after calling this constructor.
*
* @since 2.0
- *
- * @see Construct()
*/
GregorianCalendar(void);
@@ -104,17 +103,17 @@ public:
/**
- * Initializes this instance of %GregorianCalendar with the current GMT time zone and the system locale.
- * The time zone is used for the zone offset and the DST offset.
- * An instance has weekdata which are the first of week, minimal days in the first week, weekend on set and weekend cease.
- * The weekdata are set as default values by the locale.
- *
- * @since 2.0
- *
- * @return An error code
- * @exception E_SUCCESS The method is successful.
- * @exception E_OUT_OF_MEMORY The memory is insufficient.
- */
+ * Initializes this instance of %GregorianCalendar with the current GMT time zone and the system locale. @n
+ * The time zone is used for the zone offset and the DST offset.
+ * An instance has weekdata which is the first of week, minimal days in the first week, weekend on set and weekend cease.
+ * The weekdata is set to default values by the locale.
+ *
+ * @since 2.0
+ *
+ * @return An error code
+ * @exception E_SUCCESS The method is successful.
+ * @exception E_OUT_OF_MEMORY The memory is insufficient.
+ */
result Construct(void);
@@ -134,8 +133,8 @@ public:
/**
* Initializes this instance of %GregorianCalendar based on the current time in the specified time zone with the system locale. @n
* The @c timeZone is used for the zone offset and the DST offset.
- * An instance has weekdata which are the first of week, minimal days in the first week, weekend on set, and weekend cease.
- * The weekdata are set as default values by the locale.
+ * An instance has weekdata which is the first of week, minimal days in the first week, weekend on set, and weekend cease.
+ * The weekdata is set to default values by the locale.
*
* @since 2.0
*
@@ -150,23 +149,23 @@ public:
/**
* Initializes this instance of %GregorianCalendar based on the current time in the GMT time zone with the specified @c locale.
* The time zone is used for the zone offset and the DST offset.
- * An instance has weekdata which are the first of week, minimal days in the first week, weekend on set, and weekend cease.
- * The weekdata are set as default values by the specified @c locale.
+ * An instance has weekdata which is the first of week, minimal days in the first week, weekend on set, and weekend cease.
+ * The weekdata is set to default values by the specified @c locale.
*
* @if OSPCOMPAT
* @brief [Compatibility]
* @endif
* @since 2.0
* @if OSPCOMPAT
- * @compatibility This method has compatibility issues with OSP compatibile applications. @n
- * For more information, see @ref CompGregorianCalendarConstructPage "here".
+ * @compatibility This method has compatibility issues with OSP compatible applications. @n
+ * For more information, see @ref CompGregorianCalendarConstructPage "here".
* @endif
*
* @return An error code
- * @param[in] locale An instance of Locale
- * @exception E_SUCCESS The method is successful.
- * @exception E_OUT_OF_MEMORY The memory is insufficient.
- * @exception E_INVALID_ARG The specified @c locale is invalid.
+ * @param[in] locale An instance of Locale
+ * @exception E_SUCCESS The method is successful.
+ * @exception E_OUT_OF_MEMORY The memory is insufficient.
+ * @exception E_INVALID_ARG The specified @c locale is invalid.
*/
result Construct(const Locale& locale);
@@ -174,16 +173,16 @@ public:
/**
* Initializes this instance of %GregorianCalendar based on the current time in the specified time zone with the specified system locale. @n
* The @c timeZone is used for the zone offset and the DST offset.
- * An instance has weekdata which are the first of week, minimal days in the first week, weekend on set, and weekend cease.
- * The weekdata are set as default values by the specified @c locale.
+ * An instance has weekdata which is the first of week, minimal days in the first week, weekend on set, and weekend cease.
+ * The weekdata is set to default values by the specified @c locale.
*
* @if OSPCOMPAT
* @brief [Compatibility]
* @endif
* @since 2.0
* @if OSPCOMPAT
- * @compatibility This method has compatibility issues with OSP compatibile applications. @n
- * For more information, see @ref CompGregorianCalendarConstructPage "here".
+ * @compatibility This method has compatibility issues with OSP compatible applications. @n
+ * For more information, see @ref CompGregorianCalendarConstructPage "here".
* @endif
*
* @return An error code
@@ -191,21 +190,21 @@ public:
* @param[in] locale An instance of Locale
* @exception E_SUCCESS The method is successful.
* @exception E_OUT_OF_MEMORY The memory is insufficient.
- * @exception E_INVALID_ARG The specified @c locale is invalid.
+ * @exception E_INVALID_ARG The specified @c locale is invalid.
*/
result Construct(const TimeZone& timeZone, const Locale& locale);
/**
* @if OSPCOMPAT
- * @page CompGregorianCalendarConstructPage Compatibility for Construct()
- * @section CompGregorianCalendarConstructIssueSection Issues
+ * @page CompGregorianCalendarConstructPage Compatibility for Construct()
+ * @section CompGregorianCalendarConstructIssueSection Issues
* Implementation of this method in OSP compatible applications has the following issue: @n
- * -# The method returns E_UNSUPPORTED_OPERATION if the @c locale is invalid.
+ * -# The method returns @c E_UNSUPPORTED_OPERATION if the @c locale is invalid.
*
- * @section CompGregorianCalendarConstructSolutionSection Resolutions
+ * @section CompGregorianCalendarConstructSolutionSection Resolutions
* This issue has been resolved in Tizen.
* @par When working in Tizen:
- * -# The method returns E_INVALID_ARG if the @c locale is invalid.
+ * -# The method returns @c E_INVALID_ARG if the @c locale is invalid.
* @endif
*/
@@ -213,25 +212,25 @@ public:
* Initializes this instance of %GregorianCalendar based on the specified @c year, @c month, @c day, @c hour, @c minute, and @c second
* in the GMT time zone with the system locale. @n
* The time zone is used for the zone offset and the DST offset.
- * An instance has weekdata which are the first of week, minimal days in the first week, weekend on set, and weekend cease.
- * The weekdata are set as default values by the locale.
- * The Gregorian calendar is lenient: time fields are normalized when the user calls the Calendar::GetTimeField() method.
+ * An instance has weekdata which is the first of week, minimal days in the first week, weekend on set, and weekend cease.
+ * The weekdata is set to default values by the locale.
+ * The Gregorian calendar is lenient; time fields are normalized when the user calls the Calendar::GetTimeField() method.
*
* @since 2.0
*
* @return An error code
- * @param[in] year An integer value used to set the year time field
- * @param[in] month An integer value used to set the month time field @n
+ * @param[in] year The year value
+ * @param[in] month The month value @n
* The indexing is 1-based. Therefore, 1 means January.
- * @param[in] day An integer value used to set the date time field
- * @param[in] hour An integer value used to set the hour time field
- * @param[in] minute An integer value used to set the minute time field
- * @param[in] second An integer value used to set the second time field
+ * @param[in] day The date value
+ * @param[in] hour The hour value
+ * @param[in] minute The minute value
+ * @param[in] second The second value
* @exception E_SUCCESS The method is successful.
- * @exception E_INVALID_ARG An argument is invalid.
+ * @exception E_INVALID_ARG A specified argument is invalid.
* @exception E_OUT_OF_MEMORY The memory is insufficient.
- * @exception E_OUT_OF_RANGE In this method, time fields of this instance are calculated. @n
- * If the value of the time fields goes out of range, this exception is returned.
+ * @exception E_OUT_OF_RANGE In this method, the time fields of this instance are calculated. @n
+ * If the value of the time fields go out of range, this exception is returned.
*/
result Construct(int year, int month, int day, int hour = 0, int minute = 0, int second = 0);
@@ -239,8 +238,8 @@ public:
/**
* Initializes this instance of %GregorianCalendar based on the specified date and time in the GMT time zone with the system locale. @n
* The time zone is used for the zone offset and the DST offset.
- * An instance has weekdata which are the first of week, minimal days in the first week, weekend on set, and weekend cease.
- * The weekdata are set as default values by the locale.
+ * An instance has weekdata which is the first of week, minimal days in the first week, weekend on set, and weekend cease.
+ * The weekdata is set to default values by the locale.
*
* @since 2.0
*
@@ -248,43 +247,46 @@ public:
* @param[in] dateTime An instance of Tizen::Base::DateTime
* @exception E_SUCCESS The method is successful.
* @exception E_OUT_OF_MEMORY The memory is insufficient.
- * @exception E_INVALID_ARG The specified @c dateTime is invalid.
- * @exception E_OUT_OF_RANGE In this method, time fields of this instance are calculated. @n
- * If the value of the time fields goes out of range, this exception is returned.
+ * @exception E_INVALID_ARG The specified @c dateTime is invalid.
+ * @exception E_OUT_OF_RANGE In this method, the time fields of this instance are calculated. @n
+ * If the value of the time fields go out of range, this exception is returned.
*/
result Construct(const Tizen::Base::DateTime& dateTime);
/**
* Adds the specified amount to the specified time field, based on the calendar rules. @n
- * It is equivalent to calling Set(field, GetTimeField(field)+amount) with two adjustments. @n
+ * It is equivalent to calling Set(field, GetTimeField(field)+amount) with the following two adjustments: @n
*
- * @b Add @b Rule1: The value of @c field after the call minus the value of @c field before the call is delta, modulo any overflow that has occurred in @c field.
- * Overflow occurs when the @c field value exceeds its range and, as a result, the next larger field is incremented or decremented and the @c field value is adjusted back into its range. @n
+ * @b Add @b Rule1: The value of @c field after the call minus the value of @c field before the call is delta, modulo any
+ * overflow that has occurred in @c field. Overflow occurs when the @c field value exceeds its range and, as a result,
+ * the next larger field is incremented or decremented and the @c field value is adjusted back into its range. @n
*
- * @b Add @b Rule2: If a smaller field is expected to be invariant, but it is impossible for it to be equal to its prior value because of
- * changes in its minimum or maximum value after the @c field value is changed, then its value is adjusted to the closest possible value. @n
+ * @b Add @b Rule2: If a smaller field is expected to be invariant, but it is impossible for it to be equal to its prior
+ * value because of changes in its minimum or maximum value after the @c field value is changed, then its value is adjusted
+ * to the closest possible value. @n
*
- * A smaller field represents a smaller unit of time. The TIME_FIELD_HOUR field is smaller than the TIME_FIELD_DAY_OF_MONTH field.
+ * A smaller field represents a smaller unit of time. The @c TIME_FIELD_HOUR field is smaller than the @c TIME_FIELD_DAY_OF_MONTH field.
* No adjustment is made to smaller fields that are not expected to be invariant.
* The calendar system determines what fields are expected to be invariant. @n
*
- * In addition, this method forces re-computation of the calendar's milliseconds and all time fields immediately.
+ * In addition, this method forces re-computation of the calendar's milliseconds and all the time fields immediately.
* @n
- * For example, consider a %GregorianCalendar set to Oct. 31. 2004. Calling AddTimeField(TIME_FIELD_MONTH, 13) sets the calendar to Nov. 30. 2005.
- * The TIME_FIELD_MONTH field is set to TIME_FIELD_NOVEMBER by @b Rule1, since adding 13 months to October gives November of the next year. Since
- * the TIME_FIELD_DAY_OF_MONTH cannot be 31 in November in a %GregorianCalendar, TIME_FIELD_DAY_OF_MONTH is set to 30 by @b Rule2.
+ * For example, consider a %GregorianCalendar set to Oct. 31. 2004. Calling AddTimeField(@c TIME_FIELD_MONTH, 13) sets the calendar to Nov. 30. 2005.
+ * The @c TIME_FIELD_MONTH field is set to @c TIME_FIELD_NOVEMBER by @b Rule1, since adding 13 months to October gives the month
+ * value as November of the next year. Since the @c TIME_FIELD_DAY_OF_MONTH cannot be 31 in November in a %GregorianCalendar,
+ * @c TIME_FIELD_DAY_OF_MONTH is set to 30 by @b Rule2.
*
* @since 2.0
*
* @return An error code
- * @param[in] field The time field
- * @param[in] amount The amount to add
- * @exception E_SUCCESS The method is successful.
- * @exception E_INVALID_ARG The specified @c field is invalid.
- * @exception E_OUT_OF_RANGE In this method, time fields of this instance are calculated. @n
- * If the value of the time fields goes out of range, this exception is returned.
- * @remarks The TIME_FIELD_EXTENDED_YEAR and TIME_FIELD_YEAR_WOY fields cannot be added.
+ * @param[in] field The time field
+ * @param[in] amount The amount to add
+ * @exception E_SUCCESS The method is successful.
+ * @exception E_INVALID_ARG The specified @c field is invalid.
+ * @exception E_OUT_OF_RANGE In this method, the time fields of this instance are calculated. @n
+ * If the value of the time fields go out of range, this exception is returned.
+ * @remarks The @c TIME_FIELD_EXTENDED_YEAR and @c TIME_FIELD_YEAR_WOY fields cannot be added.
*/
virtual result AddTimeField(TimeField field, int amount);
@@ -296,10 +298,10 @@ public:
* @since 2.0
*
* @return An integer value indicating the actual minimum value
- * @param[in] field The time field
- * @exception E_SUCCESS The method is successful.
- * @exception E_INVALID_ARG The specified time field is invalid.
- * @remarks The specific error code can be accessed using the GetLastResult() method.
+ * @param[in] field The time field
+ * @exception E_SUCCESS The method is successful.
+ * @exception E_INVALID_ARG The specified time field is invalid.
+ * @remarks The specific error code can be accessed using the GetLastResult() method.
*/
virtual int GetActualMinTimeField(TimeField field) const;
@@ -311,23 +313,22 @@ public:
* @since 2.0
*
* @return An integer value indicating the actual maximum value
- * @param[in] field The time field
- * @exception E_SUCCESS The method is successful.
- * @exception E_INVALID_ARG The specified time field is invalid.
-
- * @remarks The specific error code can be accessed using the GetLastResult() method.
+ * @param[in] field The time field
+ * @exception E_SUCCESS The method is successful.
+ * @exception E_INVALID_ARG The specified time field is invalid.
+ * @remarks The specific error code can be accessed using the GetLastResult() method.
*/
virtual int GetActualMaxTimeField(TimeField field) const;
- /*
+ /**
* Gets the Gregorian Calendar change date. @n
* This is the point when the switch from Julian dates to Gregorian dates occurred.
- * Default is 00:00:00 local time, October 15, 1582. Previous to this the time and date are Julian dates.
+ * Default is 00:00:00 local time, October 15, 1582. Previous to this, the time and date are Julian dates.
*
* @since 2.0
*
- * @return The milliseconds which is the Gregorian cutover time for this calendar
+ * @return The Gregorian cutover time for this calendar in milliseconds
*/
long long GetGregorianChange(void) const;
@@ -338,7 +339,7 @@ public:
* @since 2.0
*
* @return An instance of CalendarType representing the calendar type of the current instance of Calendar @n
- * In this case, CALENDAR_GREGORIAN.
+ * In this case, @c CALENDAR_GREGORIAN.
*/
virtual CalendarType GetType(void) const;
@@ -351,10 +352,10 @@ public:
* @param[out] isInDst Set to @c true if the current date is in DST, @n
* else @c false
* @exception E_SUCCESS The method is successful.
- * @exception E_OUT_OF_RANGE In this method, time fields of this instance are calculated. @n
- * If the value of the time fields goes out of range, this exception is returned.
- * @exception E_INVALID_STATE In this method, time fields of this instance are calculated. @n
- * If any time field value previously set is invalid, this exception is returned.
+ * @exception E_OUT_OF_RANGE In this method, time fields of this instance are calculated. @n
+ * If the value of the time fields go out of range, this exception is returned.
+ * @exception E_INVALID_STATE In this method, time fields of this instance are calculated. @n
+ * If any time field value previously set is invalid, this exception is returned.
*/
virtual result IsInDst(bool& isInDst) const;
@@ -371,18 +372,18 @@ public:
bool IsLeapYear(int year) const;
- /*
+ /**
* Sets the Gregorian Calendar change date. @n
* This is the point when the switch from Julian dates to Gregorian dates occurred.
* Default is 00:00:00 local time, Oct 15, 1582. Previous to this, dates are in the Julian calendar.
*
- * To obtain a pure Julian calendar, set the change @c change to MAX_MILLISECOND.
- * To obtain a pure Gregorian calendar, set the change @c change to MIN_MILLISECOND.
+ * To obtain a pure Julian calendar, set @c change to @c MAX_MILLISECOND.
+ * To obtain a pure Gregorian calendar, set @c change to @c MIN_MILLISECOND.
*
* @since 2.0
*
* @return An error code
- * @param[in] change The given Gregorian cutover date
+ * @param[in] change The Gregorian cutover date
* @exception E_SUCCESS The method is successful.
* @exception E_OUT_OF_MEMORY The memory is insufficient.
*/
@@ -390,7 +391,7 @@ public:
/**
* Rolls up or down as per the specified amount in the specified field. @n
- * This method overrides Calendar(). @n
+ * This method overrides Calendar().Roll(TimeField, int). @n
* For more details, refer to Tizen::Locales::Calendar::Roll(TimeField, int).
*
* @since 2.0
@@ -400,37 +401,37 @@ public:
* @param[in] amount The amount to roll up/down
* @exception E_SUCCESS The method is successful.
* @exception E_INVALID_STATE In this method, time fields of this instance are calculated. @n
- * If any time field value previously set is invalid, this exception is returned.
- * @exception E_INVALID_ARG The specified @c field is invalid (for example, TIME_FIELD_DST_OFFSET, TIME_FIELD_ZONE_OFFSET).
- * @exception E_OUT_OF_RANGE In this method, time fields of this instance are calculated. @n
- * If the value of the time fields goes out of range, this exception is returned.
+ * If any time field value previously set is invalid, this exception is returned.
+ * @exception E_INVALID_ARG The specified @c field is invalid (for example, @c TIME_FIELD_DST_OFFSET, @c TIME_FIELD_ZONE_OFFSET).
+ * @exception E_OUT_OF_RANGE In this method, time fields of this instance are calculated. @n
+ * If the value of the time fields go out of range, this exception is returned.
*/
virtual result Roll(TimeField field, int amount);
- /*
- * Gets the millisecond which is midnight, local time at or before the Gregorian cutover.
+ /**
+ * Gets the midnight, local time at or before the Gregorian cutover in milliseconds.
*
* @since 2.0
*
- * @return The millisecond which is midnight, local time at or before the Gregorian cutover
- * If this method fails, @c -1 is returned.
+ * @return The midnight, local time at or before the Gregorian cutover in milliseconds. @n
+ * If this method fails, @c -1 is returned. @n
* The specific error code can be accessed using the GetLastResult() method.
*/
long long GetNormalizedGregorianCutover(void) const;
- /*
+ /**
* Gets the year of the Gregorian cutover, with @c 0 representing 1 BC, @c -1 representing 2 BC, and so on.
*
* @since 2.0
*
- * @return The year of the Gregorian cutover
- * If this method fails, @c -1 is returned.
+ * @return The year of the Gregorian cutover @n
+ * If this method fails, @c -1 is returned. @n
* The specific error code can be accessed using the GetLastResult() method.
*/
int GetGregorianCutoverYear(void) const;
- /*
+ /**
* Gets the Julian day number of the Gregorian cutover.
*
* @since 2.0
@@ -440,7 +441,7 @@ public:
int GetCutoverJulianDay(void) const;
- /*
+ /**
* Checks whether the current calendar is a Gregorian calendar or not.
*
* @since 2.0
@@ -528,14 +529,14 @@ private:
public:
/*
- * Defines the length of months.
+ * The length of months.
*
* @since 2.0
*/
static const int MONTH_LENGTH[24];
/*
- * Defines the days of a year.
+ * The days of a year.
*
* @since 2.0
*/