Fix locale docs as suggested by Adrien, more work still needed

docs/user/locale/DateFormat.dox

@@ -16,7 +16,7 @@
 	\file DateFormat.h
 	\ingroup locale
 	\ingroup libbe
-	\brief Contains BDateFormat class, a date formatter.
+	\brief Contains BDateFormat class, a date formatter and parser.
 */
 
 
@@ -35,6 +35,8 @@
 	\brief Locale constructor.
 
 	\param locale The locale to use, can be \c NULL for the default locale.
+
+	\since Haiku R1
 */
 
 
@@ -45,6 +47,8 @@
 
 	\param language The \a language to use.
 	\param format The formatting convention to use.
+
+	\since Haiku R1
 */
 
 
@@ -81,7 +85,7 @@
 	\returns The number of bytes written during the date formatting.
 	\retval B_ERROR Unable to lock the BLocale.
 	\retval B_NO_MEMORY Ran out of memory while creating the object.
-	\retval B_BAD_VALUE CheckedArrayByteSink overflowed.
+	\retval B_BAD_VALUE There was not enough space to store the result.
 
 	\since Haiku R1
 */
@@ -97,7 +101,8 @@
 	\param time The time (in seconds since epoch) to format
 	\param style Specify the long format (with day name, full
 		month name) or the short format, 08/12/2010 or similar.
-	\param timeZone The time zone.
+	\param timeZone Specifies the time zone to use, if \c NULL, use the
+	       system default time zone (usually UTC).
 
 	\returns A status code.
 	\retval B_OK Everything went fine.
@@ -113,11 +118,19 @@
 		int*& fieldPositions, int& fieldCount, const time_t time,
 		const BDateFormatStyle style) const
 	\brief Fills in \a string with a custom formatted date according to the
-	       given parameters for the locale.
+	       given parameters for the locale and fills out an array of
+	       \a fieldPositions which must be freed by the caller and a
+	       \a fieldCount which contains the number of positions.
+
+	The positions are offsets in the string at which each element of the date
+	(day, month, year, etc) and the separator starting positions. These
+	can be used, for example, to split the string into parts to use in a
+	locale-aware set of BMenuFields to edit the date in the local format.
 
 	\param string The string buffer to fill with the formatted date.
-	\param fieldPositions An array of date field positions to use.
+	\param fieldPositions An array of date field positions to be filled out.
-	\param fieldCount The number of \a fields in \a fieldPositions.
+	\param fieldCount The number of \a fields in \a fieldPositions to be
+	       filled out.
 	\param time The time (in seconds since epoch) to format
 	\param style Specify the long format (with day name, full
 		month name) or the short format, 08/12/2010 or similar.
@@ -125,8 +138,9 @@
 	\returns A status code.
 	\retval B_OK Everything went fine.
 	\retval B_ERROR Unable to lock the BLocale.
-	\retval B_NO_MEMORY Ran out of memory while creating the object.
+	\retval B_NO_MEMORY Ran out of memory while creating the \a string buffer
-	\retval B_BAD_VALUE An error occurred while performing the date formatting.
+	        or \a fieldPositions array.
+	\retval B_BAD_VALUE There was not enough space to store the result.
 
 	\since Haiku R1
 */
@@ -137,25 +151,27 @@
 		BDateFormatStyle style) const
 	\brief Get the type of each field in the date format of the locale.
 
-	This method is most often used in combination with FormatDate().
+	This method is most often used in combination with the version of Format()
-	FormatDate() gives you the offset of each field in a formatted string,
+	that takes a fieldPositions parameter. Format() gives you the offset of
-	and GetDateFields() gives you the type of the field at a given offset.
+	each field in a formatted string, and GetFields() gives you the type of
-	With these informations, you can handle the formatted date string as
+	the field at a given offset. With these informations, you can handle the
-	a list of fields that you can split and alter at will.
+	formatted date string as a list of fields that you can split and alter at
+	will.
 
-	\param fields Pointer to the fields object.
+	\param fields Pointer to the array of BDateElement objects.
-	\param fieldCount The number of fields.
+	\param fieldCount The number of fields in \a fields.
-	\param style Specify the long format (with day name, full
+	\param style Specify the long format (with day name, full month name)
-	       month name) or the short format, 08/12/2010 or similar.
+	       or the short format, "08/12/2010" or similar.
 
 	\returns A status code.
 	\retval B_OK Everything went fine.
 	\retval B_ERROR Unable to lock the BLocale.
 	\retval B_NO_MEMORY Ran out of memory while creating the object.
-	\retval B_BAD_VALUE An error occurred while getting the date fields.
+	\retval B_BAD_VALUE Bad or invalid \a fields data.
 
-	\sa BDateFormat::GetTimeFields(BDateElement*& fields, int& fieldCount,
+	\sa BDateFormat::GetFields(BDateElement*&, int&, BTimeFormatStyle) const
-		BTimeFormatStyle style) const
+	\sa BDateFormat::Format(BString&, int*&, int&, const time_t,
+		const BDateFormatStyle) const
 
 	\since Haiku R1
 */

docs/user/locale/DateTimeFormat.dox

@@ -16,7 +16,7 @@
 	\file DateTimeFormat.h
 	\ingroup locale
 	\ingroup libbe
-	\brief Contains BDateTimeFormat class, a datetime formatter.
+	\brief Contains BDateTimeFormat class, a datetime formatter and parser.
 */
 
 
@@ -82,7 +82,7 @@
 	\returns The number of bytes written during the datetime formatting.
 	\retval B_ERROR Unable to lock the BLocale.
 	\retval B_NO_MEMORY Ran out of memory while creating the object.
-	\retval B_BAD_VALUE CheckedArrayByteSink overflowed.
+	\retval B_BAD_VALUE There was not enough space to store the result.
 
 	\since Haiku R1
 */
@@ -97,9 +97,10 @@
 
 	\param buffer The string buffer to fill with the formatted date.
 	\param time The time (in seconds since epoch) to format
-	\param dateStyle Specify the long format or the short format of the date.
+	\param dateStyle Specifies the long format or the short format of the date.
-	\param timeStyle Specify the long format or the short format of the time.
+	\param timeStyle Specifies the long format or the short format of the time.
-	\param timeZone The time zone.
+	\param timeZone Specifies the time zone to use, if \c NULL, use the
+	       system default time zone (usually UTC).
 
 	\returns A status code.
 	\retval B_OK Everything went fine.

docs/user/locale/DurationFormat.dox

@@ -16,7 +16,7 @@
 	\file DurationFormat.h
 	\ingroup locale
 	\ingroup libbe
-	\brief Contains BDurationFormat class, a time interval formatter.
+	\brief Contains BDurationFormat class, a time interval formatter and parser.
 */
 
 
@@ -106,7 +106,7 @@
 
 	\returns A status code.
 	\retval B_OK Everything went fine.
-	\retval B_BAD_VALUE Buffer was \c NULL.
+	\retval B_BAD_VALUE \a buffer was \c NULL or invalid.
 	\retval B_ERROR Formatting error.
 
 	\since Haiku R1

docs/user/locale/NumberFormat.dox

@@ -16,7 +16,7 @@
 	\file NumberFormat.h
 	\ingroup locale
 	\ingroup libbe
-	\brief Contains BNumberFormat class, a number formatter.
+	\brief Contains BNumberFormat class, a number formatter and parser.
 */
 
 
@@ -62,7 +62,7 @@
 	\retval B_ERROR Unable to lock the BNumberFormat.
 	\retval B_NO_MEMORY Ran out of memory while creating the NumberFormat
 	        object.
-	\retval B_BAD_VALUE An error occurred while formatting the number.
+	\retval B_BAD_VALUE There was not enough space to store the result.
 
 	\sa BNumberFormat::Format(char* string, size_t maxSize,
 		int32 value) const
@@ -87,7 +87,7 @@
 	\retval B_ERROR Unable to lock the BNumberFormat.
 	\retval B_NO_MEMORY Ran out of memory while creating the NumberFormat
 	        object.
-	\retval B_BAD_VALUE An error occurred while formatting the number.
+	\retval B_BAD_VALUE There was not enough space to store the result.
 
 	\sa BNumberFormat::Format(BString* string, int32 value) const
 	\sa BNumberFormat::FormatMonetary(BString* string, double value) const
@@ -110,7 +110,7 @@
 	\retval B_ERROR Unable to lock the BNumberFormat.
 	\retval B_NO_MEMORY Ran out of memory while creating the NumberFormat 
 	        object.
-	\retval B_BAD_VALUE An error occurred while formatting the number.
+	\retval B_BAD_VALUE There was not enough space to store the result.
 
 	\sa BNumberFormat::Format(char* string, size_t maxSize,
 		double value) const
@@ -135,7 +135,7 @@
 	\retval B_ERROR Unable to lock the BNumberFormat.
 	\retval B_NO_MEMORY Ran out of memory while creating the NumberFormat
 	        object.
-	\retval B_BAD_VALUE An error occurred while formatting the number.
+	\retval B_BAD_VALUE There was not enough space to store the result.
 
 	\sa BNumberFormat::Format(BString* string, double value) const
 	\sa BNumberFormat::FormatMonetary(BString* string, double value) const
@@ -150,6 +150,9 @@
 	\brief Format the \c double \a value as a monetary string and put the
 	       result into \a string up to \a maxSize bytes in the current locale.
 
+	It uses the money symbol set by the Locale (€, $, ...) or the generic money
+	symbol (¤) if the locale is not country-specific.
+
 	\param string The \a string to put the monetary formatted number into.
 	\param maxSize The maximum of bytes to copy into \a string.
 	\param value The number to format as a monetary \a value.
@@ -158,7 +161,7 @@
 	\retval B_ERROR Unable to lock the BNumberFormat.
 	\retval B_NO_MEMORY Ran out of memory while creating the NumberFormat
 	        object.
-	\retval B_BAD_VALUE An error occurred while formatting the number.
+	\retval B_BAD_VALUE There was not enough space to store the result.
 
 	\sa BNumberFormat::Format(char* string, size_t maxSize, double value) const
 	\sa BNumberFormat::Format(char* string, size_t maxSize, int32 value) const
@@ -181,7 +184,7 @@
 	\retval B_ERROR Unable to lock the BNumberFormat.
 	\retval B_NO_MEMORY Ran out of memory while creating the NumberFormat
 	        object.
-	\retval B_BAD_VALUE An error occurred while formatting the number.
+	\retval B_BAD_VALUE There was not enough space to store the result.
 
 	\sa BNumberFormat::Format(BString* string, double value) const
 	\sa BNumberFormat::Format(BString* string, int32 value) const

docs/user/locale/TimeFormat.dox

@@ -16,7 +16,7 @@
 	\file TimeFormat.h
 	\ingroup locale
 	\ingroup libbe
-	\brief Contains BTimeFormat class, a time formatter.
+	\brief Contains BTimeFormat class, a time formatter and parser.
 */
 
 
@@ -32,7 +32,9 @@
 
 /*!
 	\fn BTimeFormat::BTimeFormat()
-	\brief Constructor.
+	\brief Default Constructor. The current system locale is used.
+
+	\since Haiku R1
 */
 
 
@@ -43,6 +45,8 @@
 
 	\param language The \a language to use.
 	\param format The formatting convention to use.
+
+	\since Haiku R1
 */
 
 
@@ -72,13 +76,13 @@
 
 	\param string The string buffer to fill with the formatted time.
 	\param maxSize The size of the buffer.
-	\param time The time (in seconds since epoch) to format
+	\param time The time (in seconds since midnight) to format.
 	\param style Specify the long format or the short format.
 
 	\returns The number of bytes written during the time formatting.
 	\retval B_ERROR Unable to lock the BLocale.
 	\retval B_NO_MEMORY Ran out of memory while creating the object.
-	\retval B_BAD_VALUE CheckedArrayByteSink overflowed.
+	\retval B_BAD_VALUE There was not enough space to store the result.
 
 	\since Haiku R1
 */
@@ -88,10 +92,10 @@
 	\fn status_t BTimeFormat::Format(char* string, size_t maxSize,
 		time_t time, BTimeFormatStyle style) const
 	\brief Fills in \a string with a formatted time for the given
-	       \a time, \a style, and \a timeZone for the locale.
+	       \a time, and \a style for the locale.
 
 	\param string The string buffer to fill with the formatted time.
-	\param time The time (in seconds since epoch) to format
+	\param time The time (in seconds since midnight) to format.
 	\param style Specify the long format or the short format.
 
 	\returns A status code.
@@ -99,11 +103,10 @@
 	\retval B_ERROR Unable to lock the BLocale.
 	\retval B_NO_MEMORY Ran out of memory while creating the object.
 
-	\sa BLocale::FormatDate(BString *string, time_t time,
+	\sa BLocale::FormatDate(BString*, time_t, BTimeFormatStyle,
-		BTimeFormatStyle style, const BTimeZone* timeZone) const
+		const BTimeZone*) const
-	\sa BLocale::FormatDateTime(BString* target, time_t time,
+	\sa BLocale::FormatDateTime(BString*, time_t, BTimeFormatStyle,
-		BTimeFormatStyle dateStyle, BTimeFormatStyle timeStyle,
+		BTimeFormatStyle, const BTimeZone*) const
-		const BTimeZone* timeZone) const
 
 	\since Haiku R1
 */
@@ -113,35 +116,42 @@
 	\fn status_t BTimeFormat::Format(BString& string, const time_t time,
 		const BTimeFormatStyle style, const BTimeZone* timeZone) const
 	\brief Fills in \a string with a formatted time for the given
-	       \a time and \a style for the locale.
+	       \a time, \a style, and \a timeZone for the locale.
 
 	\param string The string buffer to fill with the formatted time.
 	\param time The time (in seconds since epoch) to format.
-	\param style Specify the long format or the short format.
+	\param style Specifies whether to use the long format or short format.
-	\param timeZone The time zone to use, if \c NULL, uses the one set by the
+	\param timeZone Specifies the time zone to use, if \c NULL, use the
-	       locale.
+	       system default time zone (usually UTC).
 
 	\returns A status code.
 	\retval B_OK Everything went fine.
 	\retval B_ERROR Unable to lock the BLocale.
 	\retval B_NO_MEMORY Ran out of memory while creating the object.
-	\retval B_BAD_VALUE An error occurred during time formatting.
+	\retval B_BAD_VALUE There was not enough space to store the result.
 
 	\since Haiku R1
 */
 
 
 /*!
-	\fn status_t BTimeFormat::Format(BString& string,
+	\fn status_t BTimeFormat::Format(BString& string, int*& fieldPositions,
-		int*& fieldPositions, int& fieldCount,
+		int& fieldCount, time_t time, BTimeFormatStyle style) const
-		time_t time, BTimeFormatStyle style) const
+	\brief Fills in \a string with a custom formatted date according to the
-	\brief Fills in \a string with a custom formatted time according to the
+	       given parameters for the locale and fills out an array of
-	       given parameters for the locale.
+	       \a fieldPositions which must be freed by the caller and a
+	       \a fieldCount which contains the number of positions.
+
+	The positions are offsets in the string at which each element of the time
+	(hour, minute, second, etc) and the separator starting positions. These
+	can be used, for example, to split the string in parts to use in a
+	locale-aware set of BMenuFields to edit the time in the local format.
 
 	\param string The string buffer to fill with the formatted time.
-	\param fieldPositions An array of time field positions to use.
+	\param fieldPositions An array of time field positions to be filled out.
-	\param fieldCount The number of \a fields in \a fieldPositions.
+	\param fieldCount The number of \a fields in \a fieldPositions to be
-	\param time The time (in seconds since epoch) to format
+	       filled out.
+	\param time The time (in seconds since epoch) to format.
 	\param style Specify the long format (with day name, full
 		month name) or the short format, 08/12/2010 or similar.
 
@@ -149,7 +159,7 @@
 	\retval B_OK Everything went fine.
 	\retval B_ERROR Unable to lock the BLocale.
 	\retval B_NO_MEMORY Ran out of memory while creating the object.
-	\retval B_BAD_VALUE An error occurred while performing the time formatting.
+	\retval B_BAD_VALUE There was not enough space to store the result.
 
 	\since Haiku R1
 */
@@ -174,7 +184,7 @@
 	\retval B_OK Everything went fine.
 	\retval B_ERROR Unable to lock the BLocale.
 	\retval B_NO_MEMORY Ran out of memory while creating the object.
-	\retval B_BAD_VALUE An error occurred while getting the time fields.
+	\retval B_BAD_VALUE Bad or invalid \a fields data.
 
 	\since Haiku R1
 */

docs/user/locale/TimeZone.dox

@@ -25,7 +25,24 @@
 	\class BTimeZone
 	\ingroup locale
 	\ingroup libbe
-	\brief Provides information about time zones.
+	\brief Defines the time zone API which specifies a time zone, allows you to
+	       display it to the user, and converts between GMT and local time.
+
+	When displaying the name of a time zone to the user, use the display name,
+	not the time zone ID. The display name can be retrieved by the
+	BTimeZone::Name(), BTimeZone::DaylightSavingName(), BTimeZone::ShortName(),
+	and BTimeZone::ShortDaylightSavingName() methods.
+
+	- The standard name looks like "Pacific Standard Time".
+	- The daylight savings time name looks like "Pacific Daylight Time".
+	- The short name looks like either "PST" or "PDT" depending on whether the
+	  standard or daylight savings time name is requested.
+
+	\sa BTimeZone::ID()
+	\sa BTimeZone::Name()
+	\sa BTimeZone::DaylightSavingName()
+	\sa BTimeZone::ShortName()
+	\sa BTimeZone::ShortDaylightSavingName()
 
 	\since Haiku R1
 */
@@ -40,12 +57,19 @@
 	BCountry class which can enumerate all timezones in a country, or use the
 	BLocaleRoster, which knows the timezone selected by the user.
 
+	\param zoneID A time zone ID, for example, "America/Los_Angeles".
+	       This ID is used to call up a specific real-world time zone.
+	\param language The \a language to use when displaying the time zone.
+
 	\since Haiku R1
 */
 
 
 /*!
 	\fn BTimeZone::BTimeZone(const BTimeZone& other)
+	\brief Copy constructor.
+
+	\param other The BTimeZone object to copy from.
 
 	\since Haiku R1
 */
@@ -53,6 +77,9 @@
 
 /*!
 	\fn BTimeZone& BTimeZone::operator=(const BTimeZone& source)
+	\brief Assignment operator.
+
+	\param source The BTimeZone object to copy from.
 
 	\since Haiku R1
 */
@@ -60,7 +87,11 @@
 
 /*!
 	\fn const BString& BTimeZone::ID() const
-	\brief Returns the ID of the time zone.
+	\brief Returns the ID of the time zone as a BString, for example,
+	       "America/Los_Angeles".
+
+	When displaying the name of a time zone to the user, use the display name,
+	not the time zone ID.
 
 	\since Haiku R1
 */
@@ -68,7 +99,8 @@
 
 /*!
 	\fn const BString& BTimeZone::Name() const
-	\brief Returns the localized name of the time zone.
+	\brief Returns the localized name of the time zone, for example
+	       "Pacific Standard Time".
 
 	Use this method to display the time zone's name to the user.
 
@@ -78,7 +110,8 @@
 
 /*!
 	\fn const BString& BTimeZone::DaylightSavingName() const
-	\brief Returns the name of the daylight savings rules used in this timezone.
+	\brief Returns the localized daylight savings name of the time zone,
+	       for example "Pacific Daylight Time".
 
 	\since Haiku R1
 */
@@ -86,7 +119,8 @@
 
 /*!
 	\fn const BString& BTimeZone::ShortName() const
-	\brief Returns the short name of the timezone, in the user's locale.
+	\brief Returns the short name of the timezone, in the user's locale,
+	       for example "PST".
 
 	\since Haiku R1
 */
@@ -94,8 +128,8 @@
 
 /*!
 	\fn const BString& BTimeZone::ShortDaylightSavingName() const
-	\brief Returns the short name of the daylight savings rules used in this
+	\brief Returns the localized daylight savings name of the time zone,
-	       timezone.
+	       for example "PDT".
 
 	\since Haiku R1
 */
@@ -103,9 +137,14 @@
 
 /*!
 	\fn int BTimeZone::OffsetFromGMT() const
-	\brief Return the offset from GMT.
+	\brief Returns the offset, in milliseconds, between the standard time
+	       of a time zone and GMT.
 
-	The offset is a number of seconds, positive or negative.
+	Positive raw offsets are east of Greenwich, negative offsets are west of
+	Greenwich.
+
+	\return The offset as a number of milliseconds from GMT, positive
+	        or negative.
 
 	\since Haiku R1
 */
@@ -113,7 +152,10 @@
 
 /*!
 	\fn bool BTimeZone::SupportsDaylightSaving() const
-	\brief Return true if the time zone has daylight saving rules
+	\brief Returns whether or not if the time zone support daylight saving time.
+
+	\return \c true if the time zone supports daylight savings time,
+	        \c false otherwise.
 
 	\since Haiku R1
 */
@@ -121,9 +163,11 @@
 
 /*!
 	\fn status_t BTimeZone::InitCheck() const
-	\brief Return \c false if there was an error creating the timezone
+	\brief Returns whether or not the constructor initialized the time zone.
-	       for instance if you called the constructor or SetTo() with an
+
-	       invalid timezone code.
+	\return \c true if BTimeZone object was initialized successfully, \c false
+	        if there was an error initializing the BTimeZone, for instance if the
+	        constructor or SetTo() was called with an invalid timezone ID.
 
 	\since Haiku R1
 */
@@ -131,11 +175,15 @@
 
 /*!
 	\fn status_t BTimeZone::SetTo(const char* zoneCode,
-		const BLanguage* language = NULL)
+		const BLanguage* language)
-	\brief Set the timezone to another code.
+	\brief Set the BTimeZone object to use a different time zone.
 
-	\returns \c false if there was an error (likely due to an invalid
+	\param zoneCode The time zone ID to use, for example "America/Los_Angeles".
-	         timezone code.)
+	\param language The \a language to use when displaying the time zone.
+
+	\return \c true if time zone was set successfully, \c false if there was an
+	        error setting the time zone, for instance if this method was called
+	        using an invalid \a zoneCode.
 
 	\since Haiku R1
 */