From 5669793e9eaa055a06dfe829237979d2a72b7117 Mon Sep 17 00:00:00 2001
From: LaurentGom <LaurentGom@4e206d99-4929-0410-ac5d-dfc041789085>
Date: Thu, 26 Nov 2009 08:51:39 +0000
Subject: [PATCH] Updated the API documentation of Utf and String classes

git-svn-id: https://sfml.svn.sourceforge.net/svnroot/sfml/branches/sfml2@1288 4e206d99-4929-0410-ac5d-dfc041789085
---
 include/SFML/System/String.hpp | 43 ++++++++++++++++++++++++++++++++++
 include/SFML/System/Utf.hpp    | 25 ++++++++++++++++----
 2 files changed, 64 insertions(+), 4 deletions(-)

diff --git a/include/SFML/System/String.hpp b/include/SFML/System/String.hpp
index b9192c5b..90a9eff4 100644
--- a/include/SFML/System/String.hpp
+++ b/include/SFML/System/String.hpp
@@ -527,4 +527,47 @@ SFML_API String operator +(const String& left, const String& right);
 ////////////////////////////////////////////////////////////
 /// \class sf::String
 ///
+/// sf::String is a utility string class defined mainly for
+/// convenience. It is a Unicode string (implemented using
+/// UTF-32), thus it can store any character in the world
+/// (european, chinese, arabic, hebrew, etc.).
+///
+/// It automatically handles conversions from/to ANSI and
+/// wide strings, so that you can work with standard string
+/// classes and still be compatible with functions taking a
+/// sf::String.
+///
+/// \code
+/// sf::String s;
+///
+/// std::string s1 = s;  // automatically converted to ANSI string
+/// std::wstring s2 = s; // automatically converted to wide string
+/// s = "hello";         // automatically converted from ANSI string
+/// s = L"hello";        // automatically converted from wide string
+/// s += 'a';            // automatically converted from ANSI string
+/// s += L'a';           // automatically converted from wide string
+/// \endcode
+///
+/// Conversions involving ANSI strings use the default user locale. However
+/// it is possible to use a custom locale if necessary:
+/// \code
+/// std::locale locale;
+/// sf::String s;
+/// ...
+/// std::string s1 = s.ToAnsiString(locale);
+/// s = sf::String("hello", locale);
+/// \endcode
+///
+/// sf::String defines the most important functions of the
+/// standard std::string class: removing, random access, iterating,
+/// appending, comparing, etc. However it is a simple class
+/// provided for convenience, and you may have to consider using
+/// a more optimized class if your program requires complex string
+/// handling. The automatic conversion functions will then take
+/// care of converting your string to sf::String whenever SFML
+/// requires it.
+///
+/// Please note that SFML also defines a low-level, generic
+/// interface for Unicode handling, see the sf::Utf classes.
+///
 ////////////////////////////////////////////////////////////
diff --git a/include/SFML/System/Utf.hpp b/include/SFML/System/Utf.hpp
index 0a191e68..1c5afadc 100644
--- a/include/SFML/System/Utf.hpp
+++ b/include/SFML/System/Utf.hpp
@@ -45,10 +45,6 @@ namespace sf
 ////////////////////////////////////////////////////////////
 SFML_API const std::locale& GetDefaultLocale();
 
-////////////////////////////////////////////////////////////
-/// \brief Utility class providing generic functions for UTF conversions
-///
-////////////////////////////////////////////////////////////
 template <unsigned int N>
 class Utf;
 
@@ -670,3 +666,24 @@ typedef Utf<32> Utf32;
 
 
 #endif // SFML_UTF_HPP
+
+
+////////////////////////////////////////////////////////////
+/// \class sf::Utf
+///
+/// Utility class providing generic functions for UTF conversions.
+///
+/// sf::Utf is a low-level, generic interface for counting, iterating,
+/// encoding and decoding Unicode characters and strings. It is able
+/// to handle ANSI, wide, UTF-8, UTF-16 and UTF-32 encodings.
+///
+/// sf::Utf<X> functions are all static, these classes are not meant to
+/// be instanciated. All the functions are template, so that you
+/// can use any character / string type for a given encoding.
+///
+/// It has 3 specializations:
+/// \li sf::Utf<8> (typedef'd to sf::Utf8)
+/// \li sf::Utf<16> (typedef'd to sf::Utf16)
+/// \li sf::Utf<32> (typedef'd to sf::Utf32)
+///
+////////////////////////////////////////////////////////////