[patch] Doxygen fixes for std::string and std::num_get
Jonathan Wakely
cow@compsoc.man.ac.uk
Tue Jun 21 12:03:00 GMT 2005
This patch tidies up some doxygen comments. The comments for
std::string's member functions often use different names to the actual
function parameters and the num_get::get() comments refer to
num_put::do_put(). Also adds "@a" markup when referring to function
args.
* include/bits/basic_string.h, include/bits/locale_facets.h: Fix
Doxygen comments that use wrong parameter and function names.
OK for mainline, and 4.0 when it thaws?
jon
-------------- next part --------------
Index: include/bits/basic_string.h
===================================================================
RCS file: /cvs/gcc/gcc/libstdc++-v3/include/bits/basic_string.h,v
retrieving revision 1.80
diff -u -p -U9 -r1.80 basic_string.h
--- include/bits/basic_string.h 3 Jun 2005 17:07:40 -0000 1.80
+++ include/bits/basic_string.h 21 Jun 2005 12:01:56 -0000
@@ -398,19 +398,19 @@ namespace std
// arguments, per 17.4.4.4 para. 2 item 2.
/**
* @brief Default constructor creates an empty string.
*/
inline
basic_string();
/**
- * @brief Construct an empty string using allocator a.
+ * @brief Construct an empty string using allocator @a a.
*/
explicit
basic_string(const _Alloc& __a);
// NB: per LWG issue 42, semantics different from IS:
/**
* @brief Construct string with copy of value of @a str.
* @param str Source string.
*/
@@ -433,19 +433,19 @@ namespace std
basic_string(const basic_string& __str, size_type __pos,
size_type __n, const _Alloc& __a);
/**
* @brief Construct string initialized by a character array.
* @param s Source character array.
* @param n Number of characters to copy.
* @param a Allocator to use (default is default allocator).
*
- * NB: s must have at least n characters, '\0' has no special
+ * NB: @a s must have at least @a n characters, '\0' has no special
* meaning.
*/
basic_string(const _CharT* __s, size_type __n,
const _Alloc& __a = _Alloc());
/**
* @brief Construct string as copy of a C string.
* @param s Source C string.
* @param a Allocator to use (default is default allocator).
*/
@@ -630,20 +630,20 @@ namespace std
* before needing to allocate more memory.
*/
size_type
capacity() const
{ return _M_rep()->_M_capacity; }
/**
* @brief Attempt to preallocate enough memory for specified number of
* characters.
- * @param n Number of characters required.
- * @throw std::length_error If @a n exceeds @c max_size().
+ * @param res_arg Number of characters required.
+ * @throw std::length_error If @a res_arg exceeds @c max_size().
*
* This function attempts to reserve enough memory for the
* %string to hold the specified number of characters. If the
* number requested is more than max_size(), length_error is
* thrown.
*
* The advantage of this function is that if optimal code is a
* necessity and the user can determine the string length that will be
* required, the user can reserve the memory in %advance, and thus
@@ -664,36 +664,36 @@ namespace std
* Returns true if the %string is empty. Equivalent to *this == "".
*/
bool
empty() const
{ return this->size() == 0; }
// Element access:
/**
* @brief Subscript access to the data contained in the %string.
- * @param n The index of the character to access.
+ * @param pos The index of the character to access.
* @return Read-only (constant) reference to the character.
*
* This operator allows for easy, array-style, data access.
* Note that data access with this operator is unchecked and
* out_of_range lookups are not defined. (For checked lookups
* see at().)
*/
const_reference
operator[] (size_type __pos) const
{
_GLIBCXX_DEBUG_ASSERT(__pos <= size());
return _M_data()[__pos];
}
/**
* @brief Subscript access to the data contained in the %string.
- * @param n The index of the character to access.
+ * @param pos The index of the character to access.
* @return Read/write reference to the character.
*
* This operator allows for easy, array-style, data access.
* Note that data access with this operator is unchecked and
* out_of_range lookups are not defined. (For checked lookups
* see at().) Unshares the string.
*/
reference
operator[](size_type __pos)
@@ -759,19 +759,19 @@ namespace std
* @param s The C string to append.
* @return Reference to this string.
*/
basic_string&
operator+=(const _CharT* __s)
{ return this->append(__s); }
/**
* @brief Append a character.
- * @param s The character to append.
+ * @param c The character to append.
* @return Reference to this string.
*/
basic_string&
operator+=(_CharT __c)
{
this->push_back(__c);
return *this;
}
@@ -1198,46 +1198,46 @@ namespace std
size_type __pos2, size_type __n2)
{ return this->replace(__pos1, __n1, __str._M_data()
+ __str._M_check(__pos2, "basic_string::replace"),
__str._M_limit(__pos2, __n2)); }
/**
* @brief Replace characters with value of a C substring.
* @param pos Index of first character to replace.
* @param n1 Number of characters to be replaced.
- * @param str C string to insert.
- * @param n2 Number of characters from str to use.
+ * @param s C string to insert.
+ * @param n2 Number of characters from @a s to use.
* @return Reference to this string.
* @throw std::out_of_range If @a pos1 > size().
* @throw std::length_error If new length exceeds @c max_size().
*
* Removes the characters in the range [pos,pos + n1) from this string.
- * In place, the first @a n2 characters of @a str are inserted, or all
- * of @a str if @a n2 is too large. If @a pos is beyond end of string,
+ * In place, the first @a n2 characters of @a s are inserted, or all
+ * of @a s if @a n2 is too large. If @a pos is beyond end of string,
* out_of_range is thrown. If the length of result exceeds max_size(),
* length_error is thrown. The value of the string doesn't change if
* an error is thrown.
*/
basic_string&
replace(size_type __pos, size_type __n1, const _CharT* __s,
size_type __n2);
/**
* @brief Replace characters with value of a C string.
* @param pos Index of first character to replace.
* @param n1 Number of characters to be replaced.
- * @param str C string to insert.
+ * @param s C string to insert.
* @return Reference to this string.
* @throw std::out_of_range If @a pos > size().
* @throw std::length_error If new length exceeds @c max_size().
*
* Removes the characters in the range [pos,pos + n1) from this string.
- * In place, the first @a n characters of @a str are inserted. If @a
+ * In place, the first @a n characters of @a s are inserted. If @a
* pos is beyond end of string, out_of_range is thrown. If the length
* of result exceeds max_size(), length_error is thrown. The value of
* the string doesn't change if an error is thrown.
*/
basic_string&
replace(size_type __pos, size_type __n1, const _CharT* __s)
{
__glibcxx_requires_string(__s);
return this->replace(__pos, __n1, __s, traits_type::length(__s));
Index: include/bits/locale_facets.h
===================================================================
RCS file: /cvs/gcc/gcc/libstdc++-v3/include/bits/locale_facets.h,v
retrieving revision 1.99
diff -u -p -U9 -r1.99 locale_facets.h
--- include/bits/locale_facets.h 15 Feb 2005 23:29:52 -0000 1.99
+++ include/bits/locale_facets.h 21 Jun 2005 12:01:58 -0000
@@ -1944,19 +1944,19 @@ namespace std
* @param refs Passed to the base facet class.
*/
explicit
num_get(size_t __refs = 0) : facet(__refs) { }
/**
* @brief Numeric parsing.
*
* Parses the input stream into the bool @a v. It does so by calling
- * num_put::do_put().
+ * num_get::do_get().
*
* If ios_base::boolalpha is set, attempts to read
* ctype<CharT>::truename() or ctype<CharT>::falsename(). Sets
* @a v to true or false if successful. Sets err to
* ios_base::failbit if reading the string fails. Sets err to
* ios_base::eofbit if the stream is emptied.
*
* If ios_base::boolalpha is not set, proceeds as with reading a long,
* except if the value is 1, sets @a v to true, if the value is 0, sets
@@ -1973,19 +1973,19 @@ namespace std
get(iter_type __in, iter_type __end, ios_base& __io,
ios_base::iostate& __err, bool& __v) const
{ return this->do_get(__in, __end, __io, __err, __v); }
//@{
/**
* @brief Numeric parsing.
*
* Parses the input stream into the integral variable @a v. It does so
- * by calling num_put::do_put().
+ * by calling num_get::do_get().
*
* Parsing is affected by the flag settings in @a io.
*
* The basic parse is affected by the value of io.flags() &
* ios_base::basefield. If equal to ios_base::oct, parses like the
* scanf %o specifier. Else if equal to ios_base::hex, parses like %X
* specifier. Else if basefield equal to 0, parses like the %i
* specifier. Otherwise, parses like %d for signed and %u for unsigned
* types. The matching type length modifier is also used.
@@ -2037,19 +2037,19 @@ namespace std
{ return this->do_get(__in, __end, __io, __err, __v); }
#endif
//@}
//@{
/**
* @brief Numeric parsing.
*
* Parses the input stream into the integral variable @a v. It does so
- * by calling num_put::do_put().
+ * by calling num_get::do_get().
*
* The input characters are parsed like the scanf %g specifier. The
* matching type length modifier is also used.
*
* The decimal point character used is numpunct::decimal_point().
* Digit grouping is intrepreted according to numpunct::grouping() and
* numpunct::thousands_sep(). If the pattern of digit groups isn't
* consistent, sets err to ios_base::failbit.
*
@@ -2078,19 +2078,19 @@ namespace std
get(iter_type __in, iter_type __end, ios_base& __io,
ios_base::iostate& __err, long double& __v) const
{ return this->do_get(__in, __end, __io, __err, __v); }
//@}
/**
* @brief Numeric parsing.
*
* Parses the input stream into the pointer variable @a v. It does so
- * by calling num_put::do_put().
+ * by calling num_get::do_get().
*
* The input characters are parsed like the scanf %p specifier.
*
* Digit grouping is intrepreted according to numpunct::grouping() and
* numpunct::thousands_sep(). If the pattern of digit groups isn't
* consistent, sets err to ios_base::failbit.
*
* Note that the digit grouping effect for pointers is a bit ambiguous
* in the standard and shouldn't be relied on. See DR 344.
More information about the Libstdc++
mailing list