From c647837666771daf95e7d026e1b1c2dacc662bab Mon Sep 17 00:00:00 2001
From: Adrien Destugues <pulkomandy@pulkomandy.ath.cx>
Date: Sat, 29 Oct 2011 19:56:05 +0000
Subject: [PATCH]  * 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 | 58 +++++++++++++++++++++++++++++
 docs/user/locale/localeintro.dox    | 17 ++++++---
 2 files changed, 69 insertions(+), 6 deletions(-)
 create mode 100644 docs/user/locale/DurationFormat.dox

diff --git a/docs/user/locale/DurationFormat.dox b/docs/user/locale/DurationFormat.dox
new file mode 100644
index 0000000000..8177757dc9
--- /dev/null
+++ b/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, pulkomandy@pulkomandy.ath.cx
+ *
+ * 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).
+*/
diff --git a/docs/user/locale/localeintro.dox b/docs/user/locale/localeintro.dox
index 34f7e77659..db88b84dd1 100644
--- a/docs/user/locale/localeintro.dox
+++ b/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
-acts as a factory to instanciate most of the other classes. However, there are
-some cases where you will need to instanciate another class by yourself, to
-use it with custom settings. For example, you may need to format a date with
-a fixed format in english for including in an e-mail header, as it is the only
-format accepted there.
+application according to the user's preferred settings. Most of the time, you
+should be able to use the default BLocale object and its convenience methods to
+get things formatted according to the user preferences.  However, you can also
+use the various formatter classes directly when you need a more advanced
+formatting.  For example, you may need to format a date with a fixed format in
+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