* Add some details on how the Locale and the formater classes relate and which

one one should use.
 * Add documentation for BDurationFormat.


git-svn-id: file:///srv/svn/repos/haiku/haiku/trunk@42976 a95241bf-73f2-0310-859d-f6bbb57e9c96

docs/user/locale/DurationFormat.dox

@@ -0,0 +1,58 @@
+/*
+ * Copyright 2011, Haiku. All rights reserved.
+ * Distributed under the terms of the MIT License.
+ *
+ * Authors:
+ *		Adrien Destugues, [email protected]
+ *
+ * Corresponds to:
+ *		/trunk/headers/os/locale/DurationFormat.h	 rev 42944
+ *		/trunk/src/kits/locale/DurationFormat.cpp	 rev 42944
+ */
+
+
+/*!
+  \class BDurationFormat
+  \ingroup locale
+  \brief Formatter for time interfals
+
+  BDurationFormat is a formatter for time intervals. A time interval is defined
+  by its start and end values, and the result is a string such as
+  "1 hour, 2 minutes, 28 seconds".
+*/
+
+
+/*!
+  \fn BDurationFormat::BDurationFormat(const BString& separator)
+  \brief Constructor.
+
+  \warning Creating a BDurationFormat is a costly operation. Most of the time,
+  you most likely want to use the default one through the BLocale class.
+
+  The separator string will be appended between the elements of formated
+  durations.
+*/
+
+
+/*!
+  \fn void BDurationFormat::SetSeparator(cosnt BString& separator)
+  \brief Replace the spearator for this formatter.
+*/
+
+
+/*!
+  \fn status_t BDurationForamt::SetLocale(const BLocale* locale)
+  \brief Sets the locale for this formatter.
+*/
+
+
+/*!
+  \fn status_t BDurationFormat::Format(bigtime_t startValue,
+  	bigtime_t endValue, BString* buffer, time_unit_style = B_TIME_UNIT_FULL)
+	const;
+  \brief Formats a duration defined by its start and end values.
+
+The start and end values are in milliseconds. The result is appeded to the
+buffer. The full time style uses full words (hours, minuts, seconds), while the
+shot one uses units (h, m, s).
+*/

docs/user/locale/localeintro.dox

@@ -8,12 +8,17 @@ dates, and times in a way that match the locale preferences of the user.
 
 The main way to access locale data is through the be_locale_roster. This is a
 global instance of the BLocaleRoster class, storing the data for localizing an
-application according to the user's preferred settings. The locale roster also
+application according to the user's preferred settings. Most of the time, you
-acts as a factory to instanciate most of the other classes. However, there are
+should be able to use the default BLocale object and its convenience methods to
-some cases where you will need to instanciate another class by yourself, to
+get things formatted according to the user preferences.  However, you can also
-use it with custom settings. For example, you may need to format a date with
+use the various formatter classes directly when you need a more advanced
-a fixed format in english for including in an e-mail header, as it is the only
+formatting.  For example, you may need to format a date with a fixed format in
-format accepted there.
+english for including in an e-mail header, as it is the only format accepted
+there.
+
+Note that creating a new format is a costly operation. The idea is that you
+create your format object once and reuse it accross your application to format
+all the stuff that needs it.
 
 Unlike the other kits in Haiku, the Locale kit does not live in libbe. When
 building a localized application, you have to link it to liblocale.so. If you