This is the mail archive of the
libstdc++@gcc.gnu.org
mailing list for the libstdc++ project.
Re: [patch] Fix comment typos in std_valarray.h
On 27 Jul, Jonathan Wakely wrote:
> Gabriel Dos Reis wrote:
>
>> Volker Reichelt <reichelt@igpm.rwth-aachen.de> writes:
>>
>> | The following patch fixes several comment typos in std_valarray.h:
>>
>> | * Assign elements of array to values in @a v. Results are undefined
>> | - * if @a v is not the same size as this array.
>> | + * if @a v has not the same size as this array.
>>
>> I guess, that was supposed to read "if @a v is not of the same size...."
>> but, you version is fine too.
>
> Not quite.
>
> The original is fine, Gaby's version is fine, but Volker's is not good
> English. You never say "A has not B" in English, you say "A does not
> have B."
Of course. Stupid me. Sorry!
> So that should be "if @a v does not have the same size as this array."
>
> It might be technically more accurate as "if the size of @a v is not the
> same as the size of this array" but that's a bit of a mouthful.
>
> Personally I prefer the original, or "does not have."
I'll go with "does not have."
> * Returns a new valarray containing the elements of the array
> - * indicated by the slice argument. The new valarray is the size of
> + * indicated by the slice argument. The new valarray has the size of
> * the input slice. @see slice.
>
> That should probably be "has the same size as the input slice"
That's better.
> * in shifted positions. For an element with index i, the new position
> - * is (i - n) % size(). The new valarray is the same size as the
> + * is (i - n) % size(). The new valarray has the same size as the
> * current one.
>
> That's perfect.
Ok.
> - * Resize this array to be @a size and set all elements to @a c. All
> + * Resize this array to have @a size and set all elements to @a c.
>
> I don't like the original or the new version much. I would prefer
> "to have size @a size" or "to have length @a size," but I think my first
> choice would be "Resize this array to @a size." That works best if you
> substitute some value for "size" e.g. "Resize to fifteen."
Indeed.
> FWIW the standard talks about lengths, not sizes, e.g.
> "The resulting behavior is undefined if the length of the argument array
> is not equal to the length of the *this array."
OTOH you call size() to get the length :-)
> jon
Thanks for the thorough review.
Ok, here's an updated version.
Is this OK for mainline?
Should I add you, Jon, to the ChangeLog?
Regards,
Volker
2005-07-27 Volker Reichelt <reichelt@igpm.rwth-aachen.de>
* include/std/std_valarray.h: Improve grammar in comments.
===================================================================
--- gcc/libstdc++-v3/include/std/std_valarray.h 24 Nov 2004 04:11:21 -0000 1.15
+++ gcc/libstdc++-v3/include/std/std_valarray.h 27 Jul 2005 12:07:19 -0000
@@ -155,7 +155,7 @@ namespace std
* @brief Assign elements to an array.
*
* Assign elements of array to values in @a v. Results are undefined
- * if @a v is not the same size as this array.
+ * if @a v does not have the same size as this array.
*
* @param v Valarray to get values from.
*/
@@ -174,7 +174,7 @@ namespace std
* @brief Assign elements to an array subset.
*
* Assign elements of array to values in @a sa. Results are undefined
- * if @a sa is not the same size as this array.
+ * if @a sa does not have the same size as this array.
*
* @param sa Array slice to get values from.
*/
@@ -184,7 +184,7 @@ namespace std
* @brief Assign elements to an array subset.
*
* Assign elements of array to values in @a ga. Results are undefined
- * if @a ga is not the same size as this array.
+ * if @a ga does not have the same size as this array.
*
* @param ga Array slice to get values from.
*/
@@ -194,7 +194,7 @@ namespace std
* @brief Assign elements to an array subset.
*
* Assign elements of array to values in @a ma. Results are undefined
- * if @a ma is not the same size as this array.
+ * if @a ma does not have the same size as this array.
*
* @param ma Array slice to get values from.
*/
@@ -204,7 +204,7 @@ namespace std
* @brief Assign elements to an array subset.
*
* Assign elements of array to values in @a ia. Results are undefined
- * if @a ia is not the same size as this array.
+ * if @a ia does not have the same size as this array.
*
* @param ia Array slice to get values from.
*/
@@ -231,8 +231,8 @@ namespace std
* @brief Return an array subset.
*
* Returns a new valarray containing the elements of the array
- * indicated by the slice argument. The new valarray is the size of
- * the input slice. @see slice.
+ * indicated by the slice argument. The new valarray has the same size
+ * as the input slice. @see slice.
*
* @param s The source slice.
* @return New valarray containing elements in @a s.
@@ -243,8 +243,8 @@ namespace std
* @brief Return a reference to an array subset.
*
* Returns a new valarray containing the elements of the array
- * indicated by the slice argument. The new valarray is the size of
- * the input slice. @see slice.
+ * indicated by the slice argument. The new valarray has the same size
+ * as the input slice. @see slice.
*
* @param s The source slice.
* @return New valarray containing elements in @a s.
@@ -266,8 +266,8 @@ namespace std
* @brief Return a reference to an array subset.
*
* Returns a new valarray containing the elements of the array
- * indicated by the gslice argument. The new valarray is
- * the size of the input gslice. @see gslice.
+ * indicated by the gslice argument. The new valarray has
+ * the same size as the input gslice. @see gslice.
*
* @param s The source gslice.
* @return New valarray containing elements in @a s.
@@ -448,8 +448,8 @@ namespace std
*
* A new valarray is constructed as a copy of this array with elements
* in shifted positions. For an element with index i, the new position
- * is i - n. The new valarray is the same size as the current one.
- * New elements without a value are set to 0. Elements whos new
+ * is i - n. The new valarray has the same size as the current one.
+ * New elements without a value are set to 0. Elements whose new
* position is outside the bounds of the array are discarded.
*
* Positive arguments shift toward index 0, discarding elements [0, n).
@@ -465,7 +465,7 @@ namespace std
*
* A new valarray is constructed as a copy of this array with elements
* in shifted positions. For an element with index i, the new position
- * is (i - n) % size(). The new valarray is the same size as the
+ * is (i - n) % size(). The new valarray has the same size as the
* current one. Elements that are shifted beyond the array bounds are
* shifted into the other end of the array. No elements are lost.
*
@@ -482,7 +482,7 @@ namespace std
*
* Returns a new valarray with elements assigned to the result of
* applying func to the corresponding element of this array. The new
- * array is the same size as this one.
+ * array has the same size as this one.
*
* @param func Function of Tp returning Tp to apply.
* @return New valarray with transformed elements.
@@ -494,7 +494,7 @@ namespace std
*
* Returns a new valarray with elements assigned to the result of
* applying func to the corresponding element of this array. The new
- * array is the same size as this one.
+ * array has the same size as this one.
*
* @param func Function of const Tp& returning Tp to apply.
* @return New valarray with transformed elements.
@@ -504,7 +504,7 @@ namespace std
/**
* @brief Resize array.
*
- * Resize this array to be @a size and set all elements to @a c. All
+ * Resize this array to @a size and set all elements to @a c. All
* references and iterators are invalidated.
*
* @param size New array size.
===================================================================