Update the BCollator class documentation to fix a number of spelling errors and make the text clearer and easier to read. Also add a bunch of details, a few warnings and notes and other small typographical changes.

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

docs/user/locale/Collator.dox

@@ -22,204 +22,232 @@
 /*!
 	\class BCollator
 	\ingroup locale
-	\brief Class for handling collation of string
+	\brief Class for handling locale-aware collation (sorting) of strings.
 
-	BCatalog is designed to handle collations (sorting) of strings.
+	BCollator is designed to handle collation (sorting) of strings. Unlike
-	The collation is done using a set of rules that changes from a country
+	string sorting using strcmp() or similar functions that compare raw bytes
-	to another.  For example, in spanish, 'ch' is consiidered as a letter
+	the collation is done using a set of rules that changes from one locale
-	and is sorted between 'c' and 'd'. This class is alsoable to perform
+	to another. For example, in Spanish, 'ch' is considered to be a letter
-	natural sorting, so that '2' is sorted before '10', which is not the
+	and is sorted between 'c' and 'd'. This class is also able to perform
-	case when you do a simple ASCII sort.
+	natural number sorting so that 2 is sorted before 10 unlike byte-based
+	sorting.
 
-	\warning This class is not multithread-safe, as Compare() and GetKey()
+	\warning This class is not multithread-safe, as Compare() change the
-	change the ICUCollator (the strength). So if you want to use a
+		ICUCollator (the strength). So if you want to use a BCollator from
-	BCollator from more than one thread, you need to protect it with a lock.
+		more than one thread you need to protect it with a lock.
 */
 
+
 /*!
 	\fn BCollator::BCollator()
-	\brief Construct a collator for the default locale.
+	\brief Construct a collator with the default locale and strength.
 
-	Empty contructor.
+	\attention The default collator should be constructed by the BLocale
+		instead since it is aware of the currently defined locale.
+
+	This constructor uses \c B_COLLATE_PRIMARY strength.
 */
 
+
 /*!
 	\fn BCollator::BCollator(const char* locale,
 		int8 strength = B_COLLATE_PRIMARY, bool ignorePunctuation = false)
-	\brief Construct a collator for the given locale.
+	\brief Construct a collator for the given \a locale and \a strength.
 
 	This constructor loads the data for the given locale. You can also
-	adjust the strength and tell if the collator should take punctuation
+	set the \a strength and choose if the collator should take
-	into account when sorting.
+	punctuation into account or not.
 
-	\param locale The \a locale.
+	\param locale The \a locale to build the constructor for.
-	\param strength The collator class provide four level of strength. These
+	\param strength The collator class provide four level of \a strength.
-		define the handling of various things.
 		\li \c B_COLLATE_PRIMARY doesn't differentiate e from é,
 		\li \c B_COLLATE_SECONDARY takes letter accents into account,
 		\li \c B_COLLATE_TERTIARY is case sensitive,
 		\li \c B_COLLATE_QUATERNARY is very strict. Most of the time you
-			shouldn't need to go that far.
+			shouldn't need to go this far.
-	\param ignorePunctuation Ignore punctuation in the Collator when sorting.
+	\param ignorePunctuation Ignore punctuation during sorting.
 */
 
+
 /*!
 	\fn BCollator::BCollator(BMessage* archive)
 	\brief Unarchive a collator from a message.
 
-	\param archive The message to unarchive the BCollator from.
+	\param archive The message to unarchive the BCollator object from.
 */
 
+
 /*!
 	\fn BCollator::BCollator(const BCollator& other)
 	\brief Copy constructor.
 
-	Constructs a BCollator by making a copy of another BCollator.
+	Copies a BCollator object from another BCollator object.
 
 	\param other The BCollator to copy from.
 */
 
+
 /*!
 	\fn BCollator::~BCollator()
-	\brief Destructor.
+	\brief Destructor method.
 
-	Standard destructor method.
+	Deletes the BCollator object freeing the resources it consumes.
 */
 
+
 /*!
 	\fn Bcollator& BCollator::operator=(const BCollator& other)
 	\brief Assignment operator.
 
-	\param other the BCollator to assign from.
+	\param other the BCollator object to assign from.
 */
 
+
 /*!
 	\fn void BCollator::SetDefaultStrength(int8 strength)
-	\brief Set the strength of the collator.
+	\brief Set the \a strength of the collator.
 
-	Note that the \a strength can also be given on a case-by-case basis
+	Note that the \a strength can also be chosen on a case-by-case basis
 	when calling other methods.
 
-	\param strength The collator class provide four level of strength.
+	\param strength The collator class provide four level of \a strength.
-	These define the handling of various things.
 	 \li \c B_COLLATE_PRIMARY doesn't differentiate e from é,
 	 \li \c B_COLLATE_SECONDARY takes letter accents into account,
 	 \li \c B_COLLATE_TERTIARY is case sensitive,
 	 \li \c B_COLLATE_QUATERNARY is very strict. Most of the time you
-		 shouldn't need to go that far.
+		 shouldn't need to go this far.
 */
 
+
 /*!
 	\fn int8 BCollator::DefaultStrength() const
 	\brief Get the current strength of this catalog.
 
-	\returns the current strength of this catalog.
+	\returns The current strength of the catalog.
 */
 
+
 /*!
 	\fn void BCollator::SetIgnorePunctuation(bool ignore)
-	\brief Enable or disable punctuation handling
+	\brief Enable or disable punctuation handling.
 
-	This function enables or disables the handling of punctuations.
+	This function enables or disables the handling of punctuation.
 
-	\param ignore Boolean telling if the punctuation should be ignored.
+	\param ignore Boolean indicating whether or not punctuation should
+		be ignored.
 */
 
 /*!
 	\fn bool BCollator::IgnorePunctuation() const
-	\brief Gets the behavior of the collator regarding punctuation.
+	\brief Gets the behavior of the collator with regards to punctuation.
 
-	This function returns \c true if the collator will take punctuation into
+	\returns \c true if the collator will take punctuation into account
-	account when sorting.
+	when sorting, \c false otherwise.
 */
 
-/*!
-	\fn satus_t BCollator::GetSortKey(const char* string, BString* key,
-		int8 strength) const
-	\brief Compute the sortkey of a string.
 
-	A sortkey is a modified version of the string that you can use for faster
+/*!
-	comparison with other sortkeys, using strcmp or a similar ASCII comparison.
+	\fn status_t BCollator::GetSortKey(const char* string, BString* key,
-	If you need to compare a string with other ones a lot of times, storing
+		int8 strength) const
-	the sortkey will allow you to do the comparisons faster.
+	\brief Compute the sortkey of a \a string.
+
+	The sortkey is a modified version of the input \a string that you can use
+	to perform faster comparisons with other sortkeys using strcmp() or a
+	similar comparison function. If you need to compare one string with other
+	many times, storing the sortkey will allow you to perform the comparisons
+	faster.
 
 	\param string String from which to compute the sortkey.
 	\param key The resulting sortkey.
-	\param strength The \a strength to use for computing the sortkey.
+	\param strength The \a strength to use to compute the sortkey.
 
-	\returns B_OK if everything went well.
+	\retval B_OK if everything went well.
+	\retval B_ERROR if an error occurred generating the sortkey.
 */
 
+
 /*!
 	\fn int BCollator::Compare(const char* s1, const char* s2,
 		int8 strength) const
-	\brief Compare two strings.
+	\brief Returns the difference betweens the two strings according to the
+		collation defined by the \a strength parameter.
 
-	Returns the difference betweens the two strings similar to strcmp().
+	This method should be used in place of the strcmp() function to perform
+	locale-aware comparisons.
 
 	\param s1 The first string to compare.
 	\param s2 The second string to compare.
-	\param strength The \a strength to use for comparing the strings.
+	\param strength The \a strength to use for the string comparison.
 
 	\retval 0 if the strings are equal.
 	\retval <0 if s1 is less than s2.
 	\retval >0 if s1 is greater than s2.
 */
 
+
 /*!
 	\fn bool BCollator::Equal(const char* s1, const char* s2,
 		int8 strength) const
-	\brief Checks two strings for equality.
+	\brief Compares two strings for equality.
 
-	Compares two strings for equality. Note that different strings may end
+	Note that strings that are not byte-by-byte identical may end up being
-	up being equal, for example if the differences are only in case and
+	treated as equal by this method. For example two strings may be
-	punctuation, depending on the strength used. Quaterary strength will
+	considered equal if the only differences between them are in case and
-	make this function return true only if the strings are byte-for-byte
+	punctuation, depending on the \a strength used. Using
-	identical.
+	\c B_QUANTERNARY_STRENGTH will force this method return \c true only
+	if the strings are byte-for-byte identical.
 
 	\param s1 The first string to compare.
 	\param s2 The second string to compare.
-	\param strength The \a strength to use for comparing the strings.
+	\param strength The \a strength to use for the string comparison.
 
-	\returns \c true if the strings are identical, otherwise \c false.
+	\returns \c true if the strings are identical, \c false otherwise.
 */
 
+
 /*!
 	\fn bool BCollator::Greater(cosnt char* s1, const char* s2,
 		int8 strength) const
 	\brief Determine if a string is greater than another.
 
-	\note !Greater(s1, s2) does the same thing as Greater(s2, s1)
+	\note This method is commutative meaning that !Greater(s1, s2)
+		is the same as Greater(s2, s1).
 
 	\param s1 The first string to compare.
 	\param s2 The second string to compare.
-	\param strength The \a strength to use for comparing the strings.
+	\param strength The \a strength to use for the string comparison.
 
 	\returns \c true if s1 is greater than, but not equal to, s2.
 */
 
+
 /*!
 	\fn bool BCollator::GreaterOrEqual(cosnt char* s1, const char* s2,
 		int8 strength) const
-	\brief Tell if a string is greater than another.
+	\brief Determines if one string is greater than another.
+
+	\note This method is commutative meaning that !GreaterOrEqual(s1, s2)
+		is the same as GreaterOrEqual(s2, s1).
 
 	\param s1 The first string to compare.
 	\param s2 The second string to compare.
-	\param strength The \a strength to use for comparing the strings.
+	\param strength The \a strength to use for the string comparison.
 
 	\returns \c true if s1 is greater or equal than s2.
 */
 
+
 /*!
 	\fn static BArchivable* BCollator::Instantiate(BMessage* archive)
 	\brief Unarchive the collator
 
-	This function allows you to restore a collator that you previously
+	This method allows you to restore a collator that you previously
-	archived. It is faster to do that than to buid a collator and set
+	archived. It is faster to archive and unarchive a collator than it is
-	it up by hand every time you need it with the same settings.
+	to create a new one up each time you need a BCollator object with the
+	same settings.
 
 	\param archive The message to restore the collator from.
 
-	\returns A BArchivable object containing the BCollator or \c NULL.
+	\returns A pointer to a BArchivable object containing the BCollator or
+		\c NULL if an error occurred restoring the \a archive.
 */
-