* Update locale kit documentation.

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

docs/user/locale/Catalog.dox

@@ -66,11 +66,14 @@ usually not a problem, it only means that some strings may not be translated
 properly. But if you want to provide different versions of your application, it
 may be useful to separate their catalogs.
 
+\param signature Mime-signature of the application for which to load a catalog.
+\param language The language of the catalog to load. If NULL, the user settings will be used.
+\param fingerprint The fingerprint version-info for the catalog to load. If 0, the fingerprint will
+not be checked,and any version of the catalog will be loaded.
 */
 
 /*!
 \fn const char* BCatalog::GetString(const char* string, const char* context = NULL, const char* comment = NULL)
-\fn const char* GetString(uint32 id)
 \brief Get a string from the catalog.
 
 This method access the data of the catalog and reeturns you the translated
@@ -81,6 +84,16 @@ alone is not helpful enough or there are special things to note. The comment is
 also used as a way to uniquely identify a string, so if two identical strings
 share the same context, it is still possible to provide different translations.
 
+\returns The translated string, or the one passed as a parameter if no translation was found.
+\param string The string to translate.
+\param context The context where the string is located.
+\param comment Supplementary comment for translators.
+*/
+
+/*!
+\fn const char* GetString(uint32 id)
+\brief Get a string by id from the catalog.
+
 The id based version of this method is slightly faster, as it doesn't have to
 compute the hash from the 3 parameters. However, it will fail if there is an
 hash collision, so you should still fallback to the first one in case of
@@ -89,6 +102,8 @@ another, depending on the file format they are stored in, so you shouldn't rely
 on this method unless you are sure you can keep all the catalog files under
 control.
 
+\returns The translated string if found, or an empty string.
+\param id The identifier of the string.
 */
 
 /*!
@@ -101,6 +116,10 @@ parsed by the collectcatkeys tool. This allows you, for example, to translate a
 string constant that you declared at another place, without getting a warning
 message from collectcatkeys.
 
+\returns The translated string, or the one passed as a parameter if no translation was found.
+\param string The string to translate.
+\param context The context where the string is located.
+\param comment Supplementary comment for translators.
 */
 
 
@@ -115,6 +134,9 @@ generatinga catalog with such data inside, and the current format may not
 support it. If you need to localize data that is not text, it is advised to
 handle it by yourself.
 
+\returns An error code.
+\param name The name of the data to retrieve.
+\param msg The BMessage to fillin with the data.
 */
 
 /*!
@@ -124,6 +146,8 @@ handle it by yourself.
 This function fills the sig string with the mime-signature associated to the
 catalog.
 
+\param sig The string where to copy the signature.
+\returns An error code.
 */
 
 /*!
@@ -131,6 +155,9 @@ catalog.
 \brief Get the catalog language.
 
 This function fills the lang string with the language name for the catalog.
+
+\param sig The string where to copy the language.
+\returns An error code.
 */
 
 /*!
@@ -139,6 +166,9 @@ This function fills the lang string with the language name for the catalog.
 
 This function setsfp to the fingerprint of the catalog. This allows you to check
 which version of the sourcecode this catalog was generated from.
+
+\returns An error code.
+\param fp The integer to set to the fingerprint value.
 */
 
 /*!
@@ -146,6 +176,10 @@ which version of the sourcecode this catalog was generated from.
 \brief Reload the string data.
 
 This function reloads the data for the given signature and fingerprint.
+
+\returns An error code.
+\param signature The signature of the catalog youwant to load
+\param fingerprint The fingerprint of the catalog you want to load.
 */
 
 /*!

docs/user/locale/Collator.dox

@@ -0,0 +1,140 @@
+/*!
+\class BCollator
+\ingroup locale
+\brief Class for handling collation of string
+
+BCatalog is designed to handle collations (sorting) of strings.
+The collation is done using a set of rules that changes from a country to another.
+For example, in spanish, 'ch' is consiidered as a letter and is sorted between 'c' and 'd'.
+This class is alsoable to perform natural sorting, so that '2' is sorted before '10',
+which is not the case when you do a simple ASCII sort.
+
+\warning This class is not multithread-safe, as Compare() and GetKey() change
+the ICUCollator (the strength). So if you want to use a BCollator from
+more than one thread, you need to protect it with a lock.
+
+*/
+
+/*!
+\fn BCollator::BCollator()
+\brief Construct a collator for the default locale.
+*/
+
+/*!
+\fn BCollator::BCollator(const char* locale, int8 strength = B_COLLATE_PRIMARY, bool ignorePunctiation = false)
+\brief Construct a collator for the given locale.
+
+This constructor loads the data for the given locale. You can also adjust the strength and
+tell if the collator should take punctuation into account when sorting.
+*/
+
+/*!
+\fn BCollator::BCollator(BMessage* archive)
+\brief Unarchive a collator.
+*/
+
+/*!
+\fn BCollator::BCollator(const BCollator& other)
+\brief Copy constructor.
+*/
+
+/*!
+\fn BCollator::~Bcollator()
+\brief Destructor.
+*/
+
+/*!
+\fn Bcollator& BCollator::operator=(const BColltr& other)
+\brief Assignment operator.
+*/
+
+/*!
+\fn void BCollator::SetDefaultStrength(int8 strength)
+\brief Set the strength of the collator.
+
+The collator class provide four level of strength. These define the handling of variuous
+things.
+\item B_COLLATE_PRIMARY doesn't differenciate e from é,
+\item B_COLLATE_SECONDARY takes them into account,
+\item B_COLLATE_TERTIARY is case sensitive,
+\item B_COLLATEÃ_QUATERNARY is very strict. Most of the time you shouldn't need to go that far.
+
+Note the strength can also be given on a case-by-case basis when calling other methods.
+
+\param strength The strength the catalog should use as default.
+*/
+
+/*!
+\fn int8 BCollator::DefaultStrength() const
+\brief Returns the current strength of this catalog.
+*/
+
+/*!
+\fn void BCollator::SetIgnorePunctuation(bool ignore)
+\brief Enable or disable punctuation handling
+
+This function enables or disables the handling of punctuations.
+
+\param ignore Boolean telling if the punctuation should be ignored.
+*/
+
+/*!
+\fn bool BCollator::IgnorePunctuation() const
+\brief Return the behaviour ofthe collator regarding punctuation.
+
+This function returns true if the collator will take punctuation into account when sorting.
+*/
+
+/*!
+\fn satus_t BCollator::GetSortKey(constchar* string, BString* key, int8 strength = B_COLLATE_DEFAULT) 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. If you need to compare a
+string with other ones a lot of times, storing the sortkey will allow you to do the
+comparisons faster.
+
+\param string String from which to compute the sortkey.
+\param key The resulting sortkey.
+\param strength The strength to use for computing the sortkey.
+
+\returns B_OK if everything went well.
+*/
+
+/*!
+\fn int BCollator::Compare(const char* s1, const char* s2, int8 strength = B_COLLATE_DEFAULT) const
+\brief Compare two strings.
+
+This function returns the difference betweens the two strings, in a way similar to strcmp.
+
+\param s1,s2 The strings to compare.
+\returns The comparison value. 0 if the strings are equal, negative if s1<s2, positive if s1>s2.
+*/
+
+/*!
+\fn bool Equal(const char* s1, const char* s2, int8 strength = B_COLLATE_DEFAULT) const
+\brief Checks two strings for equality.
+
+Compares two strings for equality. Note that different strings may end up being equal,
+for example if the differences are only in case and punctuation, depending on the strenght
+used. Quaterary strength will make this function return true only if the strings are
+byte-for-byte identical.
+
+\returns True if the two strings are identical.
+*/
+
+/*!
+\fn bool Greater(cosnt char* s1, const char* s2, int8 strength = B_COLLATE_DEFAULT) const)
+\brief Tell if a string is greater than another.
+
+\returns True if s1 is greater (not equal) than s2.
+
+\note !Greater(s1, s2) does the same thing as Greater(s2,s1)
+*/
+
+/*!
+\fn bool GreaterOrEqual(cosnt char* s1, const char* s2, int8 strength = B_COLLATE_DEFAULT) const)
+\brief Tell if a string is greater than another.
+
+\returns True if s1 is greater or equal to s2.
+*/

docs/user/locale/Country.dox

@@ -0,0 +1,72 @@
+/*!
+\class BCountry
+\ingroup locale
+\brief Class representing a country
+
+BCountry provides all the information about a particular country.
+This includes the country flag (as an HVIF icon), the localized name of the
+country, and the iso country code.
+
+Date, timeand numer formatting also depends to some extent of the language,
+so they are done in the BLocale classinstead.
+
+*/
+
+/*!
+\fn BCountry::BCountry(const char* languageCode, const char* countryCode)
+\fn BCountry::BCountry(const char* languageAndCountryCode)
+\fn BCountry::BCountry(const BCountry& other)
+\brief Constructor.
+
+A BCountry is constructed from a language and a country code.
+
+*/
+
+/*!
+\fn bool BCountry::GetName(BString& name) const
+\brief Get the name of the country
+
+Fills in the name parameter with the name of the country, in the user's locale.
+*/
+
+/*!
+\fn const char* BCountry::Code() const
+\brief Returns the country code.
+*/
+
+/*!
+\fn status_t BCountry::GetIcon(BBitmap* result) const;
+\brief Render the country's flag to the given BBitmap
+
+This function renders the Country's flag to the given BBitmap. The bitmap
+should already be set to the pixel format and size you want to use.
+
+The flag is stored in HVIF format and can be rendered atany size and color depth.
+
+\param result The BBitmap to drag the flag to.
+\returns B_OK if the drawing was successful.
+*/
+
+/*!
+\fn const char* GetLocalizedString(uint32 id) const;
+\brief Get one of the default localized strings for this country.
+
+The strings include monetary symbols and other similar things.
+
+*/
+
+/*!
+\fn int8 BCountry::Measurement() const
+\brief Returrns the measurement used in this country.
+
+\returns B_METRIC for the metric system, or B_US for the USA's system.
+*/
+
+/*!
+\fn int GetTimeZones(BList& timezones) const
+\brief Returns all the timeaones used in this country.
+
+The count may vary from 0 for countries where there is no data, to twelve, for Russia.
+
+\returns The number of timezones that were added to the list.
+*/

docs/user/locale/LocaleRoster.dox

@@ -0,0 +1,86 @@
+/*!
+\class BLocaleRoster
+\ingroup locale
+\brief Main class for accessingthe locale kit data
+
+The Locale Roster is the central part of the locale roster.
+It is a blobal object (be_localeÃ_roster) storing all the useful locale
+data. Other classes from the Locale Kit can be constructed on their own,
+but only hte Locale Roster allows you to do so while taking account of
+the user's locale settings.
+
+The Locale Roster also provides convenient short-hands to the most used
+methods of the Locale Kit.
+*/
+
+/*!
+\fn status_t BLocaleRoster::GetDefaultCollator(BCollator* collator) const
+\brief Get the default collator.
+*/
+
+/*!
+\fn status_t BLocaleRoster::GetDefaultLocale(BLocale* locale) const
+\brief Get the default locale.
+*/
+
+/*!
+\fn status_t BLocaleRoster::GetDefaultCountry(BCountry* country) const
+\brief Get the default country.
+*/
+
+/*!
+\fn status_t BLocaleRoster::GetDefaultLanguage(BLanguage* language) const
+\brief Get the default language.
+*/
+
+/*!
+\fn status_t BLocaleRoster::GetDefaultTimeZone(BTimeZone* timezone) const
+\brief Get the default timezone.
+*/
+
+/*!
+\fn status_t BlocaleRoster::GetLanguage(const char* languagecode, BLanguage** _language) const
+\brief Instanciate a language from its code.
+*/
+
+/*!
+\fn status_t BLocaleRoster::GetInstalledLanguages(BMessage* message) const
+\brief List the available languages
+
+This function fills the passed BMessage with one or more 'language' string
+fields, containing the language(s) code(s).
+
+*/
+
+/*!
+\fn status_t BLocaleRoster::GetAvailableCountries(BMessageÃ* message) const
+\brief List the available countries
+
+This function filles the passed BMessage with one or more 'country' string
+fields, containing the country names.
+
+*/
+
+/*!
+\fn status_t BLocaleRoster::GetInstalledCatalogs(BMessage* message, const char* sigPattern = NULL, const char* langPattern = NULL, int32 fingerprint = 0) const
+\brief Get the available locales and catalogs
+
+This function fills the passed BMessage with one or more 'locale' string
+fields, containing the locale names.
+
+The optional parameters can be used to filter the list and only get the
+locales for which a catalog is available for the given app (sigPattern, fingerprint),
+or the locales with a given language.
+*/
+
+/*!
+\fn BCatalog* BLocaleRoster::GetCatalog()
+\brief Get the current image catalog.
+
+This function returns the catalog for the calling image (application, add-on, or shared
+library). Note that it doesn't allow to specify a fingerprint. The language will be
+selected from the user preferences.
+
+\returns The catalog, if it was loaded successfully.
+\warning This function needs the image to be lined with liblocalestub.a
+*/