Change comment format to support automatic document generation using the CppDoc application.

git-svn-id: https://chromiumembedded.googlecode.com/svn/trunk@249 5089003a-bbd8-11dd-ad1f-f1f9622dbc98

include/internal/cef_string_wrappers.h

@@ -37,7 +37,9 @@
 #include <memory.h>
 #include <string>
 
+///
 // Traits implementation for wide character strings.
+///
 struct CefStringTraitsWide {
   typedef wchar_t char_type;
   typedef cef_string_wide_t struct_type;
@@ -115,7 +117,9 @@ struct CefStringTraitsWide {
 #endif // BUILDING_CEF_SHARED
 };
 
+///
 // Traits implementation for utf8 character strings.
+///
 struct CefStringTraitsUTF8 {
   typedef char char_type;
   typedef cef_string_utf8_t struct_type;
@@ -180,7 +184,9 @@ struct CefStringTraitsUTF8 {
 #endif // BUILDING_CEF_SHARED
 };
 
+///
 // Traits implementation for utf16 character strings.
+///
 struct CefStringTraitsUTF16 {
   typedef char16_t char_type;
   typedef cef_string_utf16_t struct_type;
@@ -259,7 +265,34 @@ struct CefStringTraitsUTF16 {
 #endif // BUILDING_CEF_SHARED
 };
 
-// String template.
+///
+// CEF string classes can convert between all supported string types. For
+// example, the CefStringWide class uses wchar_t as the underlying character
+// type and provides two approaches for converting data to/from a UTF8 string
+// (std::string).
+// <p>
+// 1. Implicit conversion using the assignment operator overload.
+// <pre>
+//   CefStringWide aCefString;
+//   std::string aUTF8String;
+//   aCefString = aUTF8String; // Assign std::string to CefStringWide
+//   aUTF8String = aCefString; // Assign CefStringWide to std::string
+// </pre>
+// 2. Explicit conversion using the FromString/ToString methods.
+// <pre>
+//   CefStringWide aCefString;
+//   std::string aUTF8String;
+//   aCefString.FromString(aUTF8String); // Assign std::string to CefStringWide
+//   aUTF8String = aCefString.ToString(); // Assign CefStringWide to std::string
+// </pre>
+// Conversion will only occur if the assigned value is a different string type.
+// Assigning a std::string to a CefStringUTF8, for example, will copy the data
+// without performing a conversion.
+// </p>
+// CEF string classes are safe for reading from multiple threads but not for
+// modification. It is the user's responsibility to provide synchronization if
+// modifying CEF strings from multiple threads.
+///
 template <class traits>
 class CefStringBase {
 public:
@@ -267,50 +300,64 @@ public:
   typedef typename traits::struct_type struct_type;
   typedef typename traits::userfree_struct_type userfree_struct_type;
 
+  ///
   // Default constructor.
+  ///
   CefStringBase() : string_(NULL), owner_(false) {}
   
+  ///
   // Create a new string from an existing string. Data will always be copied.
+  ///
   CefStringBase(const CefStringBase& str) : string_(NULL), owner_(false)
     { FromString(str.c_str(), str.length(), true); }
   
+  ///
   // Create a new string from an existing std::string. Data will be always
   // copied. Translation will occur if necessary based on the underlying string
   // type.
+  ///
   CefStringBase(const std::string& src) : string_(NULL), owner_(false)
     { FromString(src); }
   CefStringBase(const char* src) : string_(NULL), owner_(false)
     { FromString(std::string(src)); }
   
+  ///
   // Create a new string from an existing std::wstring. Data will be always
   // copied. Translation will occur if necessary based on the underlying string
   // type.
+  ///
   CefStringBase(const std::wstring& src) : string_(NULL), owner_(false)
     { FromWString(src); }
  CefStringBase(const wchar_t* src) : string_(NULL), owner_(false)
     { FromWString(std::wstring(src)); }
 
 #if (defined(BUILDING_CEF_SHARED) && defined(WCHAR_T_IS_UTF32))
+  ///
   // Create a new string from an existing string16. Data will be always
   // copied. Translation will occur if necessary based on the underlying string
   // type.
+  ///
   CefStringBase(const string16& src) : string_(NULL), owner_(false)
     { FromString16(src); }
   CefStringBase(const char16_t* src) : string_(NULL), owner_(false)
     { FromString16(string16(src)); }
 #endif // BUILDING_CEF_SHARED && WCHAR_T_IS_UTF32
   
+  ///
   // Create a new string from an existing character array. If |copy| is true
   // this class will copy the data. Otherwise, this class will reference the
   // existing data. Referenced data must exist for the lifetime of this class
   // and will not be freed by this class.
+  ///
   CefStringBase(const char_type* src, size_t src_len, bool copy)
     : string_(NULL), owner_(false)
     { FromString(src, src_len, copy); }
   
+  ///
   // Create a new string referencing an existing string structure without taking
   // ownership. Referenced structures must exist for the lifetime of this class
   // and will not be freed by this class.
+  ///
   CefStringBase(const struct_type* src) : string_(NULL), owner_(false)
   {
     if (!src)
@@ -325,19 +372,29 @@ public:
   // The following methods are named for compatibility with the standard library
   // string template types.
 
+  ///
   // Return a read-only pointer to the string data.
+  ///
   const char_type* c_str() const { return (string_ ? string_->str : NULL); }
   
+  ///
   // Return the length of the string data.
+  ///
   size_t length() const { return (string_ ? string_->length : 0); }
   
+  ///
   // Return the length of the string data.
+  ///
   inline size_t size() const { return length(); }
   
+  ///
   // Returns true if the string is empty.
+  ///
   bool empty() const { return (string_ == NULL || string_->length == 0); }
 
+  ///
   // Compare this string to the specified string.
+  ///
   int compare(const CefStringBase& str) const
   {
     if (empty() && str.empty())
@@ -349,7 +406,9 @@ public:
     return traits::compare(string_, str.GetStruct());
   }
   
+  ///
   // Clear the string data.
+  ///
   void clear()
   {
     if (!empty())
@@ -359,23 +418,31 @@ public:
 
   // The following methods are unique to CEF string template types.
 
+  ///
   // Returns true if this class owns the underlying string structure.
+  ///
   bool IsOwner() const { return owner_; }
   
+  ///
   // Returns a read-only pointer to the underlying string structure. May return
   // NULL if no structure is currently allocated.
+  ///
   const struct_type* GetStruct() const { return string_; }
   
+  ///
   // Returns a writable pointer to the underlying string structure. Will never
   // return NULL.
+  ///
   struct_type* GetWritableStruct()
   {
     AllocIfNeeded();
     return string_;
   }
   
+  ///
   // Clear the state of this class. The underlying string structure and data
   // will be freed if this class owns the structure.
+  ///
   void ClearAndFree()
   {
     if (!string_)
@@ -388,8 +455,10 @@ public:
     owner_ = false;
   }
 
+  ///
   // Attach to the specified string structure. If |owner| is true this class
   // will take ownership of the structure.
+  ///
   void Attach(struct_type* str, bool owner)
   {
     // Free the previous structure and data, if any.
@@ -399,9 +468,11 @@ public:
     owner_ = owner;
   }
 
+  ///
   // Take ownership of the specified userfree structure's string data. The
   // userfree structure itself will be freed. Only use this method with userfree
   // structures.
+  ///
   void AttachToUserFree(userfree_struct_type str)
   {
     // Free the previous structure and data, if any.
@@ -419,18 +490,22 @@ public:
     traits::userfree_free(str);
   }
 
+  ///
   // Detach from the underlying string structure. To avoid memory leaks only use
   // this method if you already hold a pointer to the underlying string
   // structure.
+  ///
   void Detach()
   {
     string_ = NULL;
     owner_ = false;
   }
 
+  ///
   // Create a userfree structure and give it ownership of this class' string
   // data. This class will be disassociated from the data. May return NULL if
   // this string class currently contains no data.
+  ///
   userfree_struct_type DetachToUserFree()
   {
     if (empty())
@@ -446,10 +521,12 @@ public:
     return str;
   }
 
+  ///
   // Set this string's data to the specified character array. If |copy| is true
   // this class will copy the data. Otherwise, this class will reference the
   // existing data. Referenced data must exist for the lifetime of this class
   // and will not be freed by this class.
+  ///
   bool FromString(const char_type* src, size_t src_len, bool copy)
   {
     if (src == NULL || src_len == 0) {
@@ -460,9 +537,11 @@ public:
     return traits::set(src, src_len, string_, copy) ? true : false;
   }
   
+  ///
   // Set this string's data from an existing ASCII string. Data will be always
   // copied. Translation will occur if necessary based on the underlying string
   // type.
+  ///
   bool FromASCII(const char* str)
   {
     size_t len = str ? strlen(str) : 0;
@@ -474,8 +553,10 @@ public:
     return traits::from_ascii(str, len, string_);
   }
   
+  ///
   // Return this string's data as a std::string. Translation will occur if
   // necessary based on the underlying string type.
+  ///
   std::string ToString() const
   {
     if (empty())
@@ -483,9 +564,11 @@ public:
     return traits::to_string(string_);
   }
   
+  ///
   // Set this string's data from an existing std::string. Data will be always
   // copied. Translation will occur if necessary based on the underlying string
   // type.
+  ///
   bool FromString(const std::string& str)
   {
     if (str.empty()) {
@@ -496,8 +579,10 @@ public:
     return traits::from_string(str, string_);
   }
   
+  ///
   // Return this string's data as a std::wstring. Translation will occur if
   // necessary based on the underlying string type.
+  ///
   std::wstring ToWString() const
   {
     if (empty())
@@ -505,9 +590,11 @@ public:
     return traits::to_wstring(string_);
   }
   
+  ///
   // Set this string's data from an existing std::wstring. Data will be always
   // copied. Translation will occur if necessary based on the underlying string
   // type.
+  ///
   bool FromWString(const std::wstring& str)
   {
     if (str.empty()) {
@@ -518,8 +605,10 @@ public:
     return traits::from_wstring(str, string_);
   }
 #if defined(BUILDING_CEF_SHARED)
+  ///
   // Return this string's data as a string16. Translation will occur if
   // necessary based on the underlying string type.
+  ///
   string16 ToString16() const
   {
     if (empty())
@@ -527,9 +616,11 @@ public:
     return traits::to_string16(string_);
   }
   
+  ///
   // Set this string's data from an existing string16. Data will be always
   // copied. Translation will occur if necessary based on the underlying string
   // type.
+  ///
   bool FromString16(const string16& str)
   {
     if (str.empty()) {
@@ -541,7 +632,9 @@ public:
   }
 #endif // BUILDING_CEF_SHARED
 
+  ///
   // Comparison operator overloads.
+  ///
   bool operator<(const CefStringBase& str) const
     { return (compare(str) < 0); }
   bool operator<=(const CefStringBase& str) const
@@ -555,7 +648,9 @@ public:
   bool operator!=(const CefStringBase& str) const
     { return (compare(str) != 0); }
   
+  ///
   // Assignment operator overloads.
+  ///
   CefStringBase& operator=(const CefStringBase& str)
     { FromString(str.c_str(), str.length(), true); return *this; }
   operator std::string() const { return ToString(); }
@@ -592,33 +687,6 @@ private:
 };
 
 
-// CEF string classes can convert between all supported string types. For
-// example, the CefStringWide class uses wchar_t as the underlying character
-// type and provides two approaches for converting data to/from a UTF8 string
-// (std::string).
-//
-// 1. Implicit conversion using the assignment operator overload.
-//
-//   CefStringWide aCefString;
-//   std::string aUTF8String;
-//   aCefString = aUTF8String; // Assign std::string to CefStringWide
-//   aUTF8String = aCefString; // Assign CefStringWide to std::string
-//
-// 2. Explicit conversion using the FromString/ToString methods.
-//
-//   CefStringWide aCefString;
-//   std::string aUTF8String;
-//   aCefString.FromString(aUTF8String); // Assign std::string to CefStringWide
-//   aUTF8String = aCefString.ToString(); // Assign CefStringWide to std::string
-//
-// Conversion will only occur if the assigned value is a different string type.
-// Assigning a std::string to a CefStringUTF8, for example, will copy the data
-// without performing a conversion.
-//
-// CEF string classes are safe for reading from multiple threads but not for
-// modification. It is the user's responsibility to provide synchronization if
-// modifying CEF strings from multiple threads.
-
 typedef CefStringBase<CefStringTraitsWide> CefStringWide;
 typedef CefStringBase<CefStringTraitsUTF8> CefStringUTF8;
 typedef CefStringBase<CefStringTraitsUTF16> CefStringUTF16;