[patch] Clarify doxygen comments w.r.t nulls in std::string

[Jonathan Wakely <jwakely at redhat dot com>]

A stackoverflow poster was confused by the comments on
basic_string::length() which talk about null-temrination, as it isn't
obvious that embedded nulls are not terminators.

I think this makes it clearer, but would appreciate other opinions.

(The @{ and @} commands tell doxygen to use the same comment for both
functions, to avoid duplicating the text more than already necessary
for the two string implementations.)


commit e028b1ff506e21567bb315715d4e694c36d1d006
Author: Jonathan Wakely <jwakely@redhat.com>
Date:   Fri Apr 1 11:48:26 2016 +0100

    Clarify doxygen comments w.r.t nulls in std::string
    
    	* include/bits/basic_string.h (basic_string::size,
    	basic_string::length): Clarify handling of embedded null characters.

diff --git a/libstdc++-v3/include/bits/basic_string.h b/libstdc++-v3/include/bits/basic_string.h
index 374c985..f79b531 100644
--- a/libstdc++-v3/include/bits/basic_string.h
+++ b/libstdc++-v3/include/bits/basic_string.h
@@ -783,18 +783,29 @@ _GLIBCXX_BEGIN_NAMESPACE_CXX11
 
     public:
       // Capacity:
-      ///  Returns the number of characters in the string, not including any
-      ///  null-termination.
+
+      /**
+       * @{
+       *
+       * @brief  Returns the number of characters in the string.
+       *
+       * The return value does not include the null character that follows
+       * the string contents, e.g. in the pointer returned by c_str(),
+       * but embedded null characters inside the string are part of the
+       * string contents and so they (and characters following them) are
+       * counted.
+       */
+
       size_type
       size() const _GLIBCXX_NOEXCEPT
       { return _M_string_length; }
 
-      ///  Returns the number of characters in the string, not including any
-      ///  null-termination.
       size_type
       length() const _GLIBCXX_NOEXCEPT
       { return _M_string_length; }
 
+      // @}
+
       ///  Returns the size() of the largest possible %string.
       size_type
       max_size() const _GLIBCXX_NOEXCEPT
@@ -1967,6 +1978,7 @@ _GLIBCXX_BEGIN_NAMESPACE_CXX11
       swap(basic_string& __s) _GLIBCXX_NOEXCEPT;
 
       // String operations:
+
       /**
        *  @brief  Return const pointer to null-terminated contents.
        *
@@ -3233,18 +3245,29 @@ _GLIBCXX_END_NAMESPACE_CXX11
 
     public:
       // Capacity:
-      ///  Returns the number of characters in the string, not including any
-      ///  null-termination.
+
+      /**
+       * @{
+       *
+       * @brief  Returns the number of characters in the string.
+       *
+       * The return value does not include the null character that follows
+       * the string contents, e.g. in the pointer returned by c_str(),
+       * but embedded null characters inside the string are part of the
+       * string contents and so they (and characters following them) are
+       * counted.
+       */
+
       size_type
       size() const _GLIBCXX_NOEXCEPT
       { return _M_rep()->_M_length; }
 
-      ///  Returns the number of characters in the string, not including any
-      ///  null-termination.
       size_type
       length() const _GLIBCXX_NOEXCEPT
       { return _M_rep()->_M_length; }
 
+      // @}
+
       ///  Returns the size() of the largest possible %string.
       size_type
       max_size() const _GLIBCXX_NOEXCEPT