[documentation] add detail to const and pure attributes

From some feedback I received on some of the attribute warnings
new in GCC 8 it seems that the manual could stand to be clarified
to explain why it makes no sense for a function declared with
attribute const (and pure) to return void.  The attached patch
adds a bit more text to make it clear.

In addition, I took the opportunity to clarify how attributes
on multiple declarations of the same function are treated.

Martin

On 03/27/2018 07:18 PM, Martin Sebor wrote:
> +Because a @code{pure} function can have no side-effects it does not

FWIW, I'd suggest rephrasing as:

 Because a @code{pure} function cannot have side effects

because "can have no side-effects" can be read as
"is allowed to have no side effects", which gave me pause
when I read it the first time, and is the opposite of
what you mean.

Thanks,
Pedro Alves

On 03/27/2018 01:38 PM, Pedro Alves wrote:
> On 03/27/2018 07:18 PM, Martin Sebor wrote:
>> +Because a @code{pure} function can have no side-effects it does not
>
> FWIW, I'd suggest rephrasing as:
>
>  Because a @code{pure} function cannot have side effects
>
> because "can have no side-effects" can be read as
> "is allowed to have no side effects", which gave me pause
> when I read it the first time, and is the opposite of
> what you mean.

That is what I meant: that const and pure functions are not allowed
to have any side-effects.  If they did, they could be unexpectedly
eliminated (i.e., the behavior is undefined when such a function
does have a side-effect).

I don't have a strong preference for one phrasing over the other
but they both say the same thing.  One is just ever so slightly
more emphatic.

Martin

On 03/27/2018 09:19 PM, Martin Sebor wrote:
> On 03/27/2018 01:38 PM, Pedro Alves wrote:
>> On 03/27/2018 07:18 PM, Martin Sebor wrote:
>>> +Because a @code{pure} function can have no side-effects it does not
>>
>> FWIW, I'd suggest rephrasing as:
>>
>>  Because a @code{pure} function cannot have side effects
>>
>> because "can have no side-effects" can be read as
>> "is allowed to have no side effects", which gave me pause
>> when I read it the first time, and is the opposite of
>> what you mean.
> 
> That is what I meant: that const and pure functions are not allowed
> to have any side-effects.  If they did, they could be unexpectedly
> eliminated (i.e., the behavior is undefined when such a function
> does have a side-effect).

I know, but that's not what I read the first time (and found it
odd so I had to re-read).  You can either assume that I'm the
only one that will misunderstand it on first read, or you can
swap a couple words and be sure no one will misunderstand it.

Up to you.

> 
> I don't have a strong preference for one phrasing over the other
> but they both say the same thing.  One is just ever so slightly
> more emphatic.
> 

Thanks,
Pedro Alves

On 03/27/2018 03:21 PM, Pedro Alves wrote:
> On 03/27/2018 09:19 PM, Martin Sebor wrote:
>> On 03/27/2018 01:38 PM, Pedro Alves wrote:
>>> On 03/27/2018 07:18 PM, Martin Sebor wrote:
>>>> +Because a @code{pure} function can have no side-effects it does not
>>>
>>> FWIW, I'd suggest rephrasing as:
>>>
>>>   Because a @code{pure} function cannot have side effects
>>>
>>> because "can have no side-effects" can be read as
>>> "is allowed to have no side effects", which gave me pause
>>> when I read it the first time, and is the opposite of
>>> what you mean.
>>
>> That is what I meant: that const and pure functions are not allowed
>> to have any side-effects.  If they did, they could be unexpectedly
>> eliminated (i.e., the behavior is undefined when such a function
>> does have a side-effect).
> 
> I know, but that's not what I read the first time (and found it
> odd so I had to re-read).  You can either assume that I'm the
> only one that will misunderstand it on first read, or you can
> swap a couple words and be sure no one will misunderstand it.
> 
> Up to you.

I'm chiming in a little late here, but I agree with Pedro that "can have 
no side-effects" is confusing.  I'd say "cannot have side effects" or 
"must have no side effects" instead.

Also note that non-hyphenated "side effects" seems to be preferred usage
as a noun phrase (at least it's the only form listed by m-w.com).

-Sandra

On 04/02/2018 12:09 AM, Sandra Loosemore wrote:
> On 03/27/2018 03:21 PM, Pedro Alves wrote:
>> On 03/27/2018 09:19 PM, Martin Sebor wrote:
>>> On 03/27/2018 01:38 PM, Pedro Alves wrote:
>>>> On 03/27/2018 07:18 PM, Martin Sebor wrote:
>>>>> +Because a @code{pure} function can have no side-effects it does not
>>>>
>>>> FWIW, I'd suggest rephrasing as:
>>>>
>>>>   Because a @code{pure} function cannot have side effects
>>>>
>>>> because "can have no side-effects" can be read as
>>>> "is allowed to have no side effects", which gave me pause
>>>> when I read it the first time, and is the opposite of
>>>> what you mean.
>>>
>>> That is what I meant: that const and pure functions are not allowed
>>> to have any side-effects.  If they did, they could be unexpectedly
>>> eliminated (i.e., the behavior is undefined when such a function
>>> does have a side-effect).
>>
>> I know, but that's not what I read the first time (and found it
>> odd so I had to re-read).  You can either assume that I'm the
>> only one that will misunderstand it on first read, or you can
>> swap a couple words and be sure no one will misunderstand it.
>>
>> Up to you.
>
> I'm chiming in a little late here, but I agree with Pedro that "can have
> no side-effects" is confusing.  I'd say "cannot have side effects" or
> "must have no side effects" instead.

There's nothing confusing about it.  It's an established phrase
with millions of uses and only one meaning.  According to Google
Books Ngram Viewer it's also more pervasive than either of
the two suggested alternatives:

   http://goo.gl/FgXgwi

> Also note that non-hyphenated "side effects" seems to be preferred usage
> as a noun phrase (at least it's the only form listed by m-w.com).

I'm all for using the preferred form.  I've made the change here
and submitted a separate patch to remove the hyphen from the rest
of the occurrences.

Attached is a changed patch that uses "cannot have side effects"
instead of "can have no side effects."

Martin
gcc/ChangeLog:

	* doc/extend.texi (Common Function Attributes): Clarify.
	(const attribute): Likewise.
	(pure attribute): Likewise.

Index: gcc/doc/extend.texi
===================================================================
--- gcc/doc/extend.texi	(revision 259017)
+++ gcc/doc/extend.texi	(working copy)
@@ -2275,8 +2275,11 @@ on a declaration, followed by an attribute specifi
 parentheses.  You can specify multiple attributes in a declaration by
 separating them by commas within the double parentheses or by
 immediately following an attribute declaration with another attribute
-declaration.  @xref{Attribute Syntax}, for the exact rules on
-attribute syntax and placement.
+declaration.  @xref{Attribute Syntax}, for the exact rules on attribute
+syntax and placement.  Compatible attribute specifications on distinct
+declarations of the same function are merged.  An attribute specification
+that is not compatible with attributes already applied to a declaration
+of the same function is ignored with a warning.
 
 GCC also supports attributes on
 variable declarations (@pxref{Variable Attributes}),
@@ -2499,7 +2502,7 @@ themselves to optimization such as common subexpre
 The @code{const} attribute imposes greater restrictions on a function's
 definition than the similar @code{pure} attribute below because it prohibits
 the function from reading global variables.  Consequently, the presence of
-the attribute on a function declarations allows GCC to emit more efficient
+the attribute on a function declaration allows GCC to emit more efficient
 code for some calls to the function.  Decorating the same function with
 both the @code{const} and the @code{pure} attribute is diagnosed.
 
@@ -2507,8 +2510,9 @@ both the @code{const} and the @code{pure} attribut
 Note that a function that has pointer arguments and examines the data
 pointed to must @emph{not} be declared @code{const}.  Likewise, a
 function that calls a non-@code{const} function usually must not be
-@code{const}.  It does not make sense for a @code{const} function to
-return @code{void}.
+@code{const}.  Because a @code{const} function cannot have any side
+effects it does not make sense for such a function to return @code{void}.
+Declaring such functions is diagnosed.
 
 @item constructor
 @itemx destructor
@@ -3218,6 +3222,9 @@ The @code{pure} attribute imposes similar but loos
 a function's defintion than the @code{const} attribute: it allows the
 function to read global variables.  Decorating the same function with
 both the @code{pure} and the @code{const} attribute is diagnosed.
+Because a @code{pure} function cannot have any side effects it does not
+make sense for such a function to return @code{void}.  Declaring such
+functions is diagnosed.
 
 @item returns_nonnull
 @cindex @code{returns_nonnull} function attribute

On 04/02/2018 11:34 PM, Martin Sebor wrote:
> On 04/02/2018 12:09 AM, Sandra Loosemore wrote:
>> On 03/27/2018 03:21 PM, Pedro Alves wrote:
>>> On 03/27/2018 09:19 PM, Martin Sebor wrote:
>>>> On 03/27/2018 01:38 PM, Pedro Alves wrote:
>>>>> On 03/27/2018 07:18 PM, Martin Sebor wrote:
>>>>>> +Because a @code{pure} function can have no side-effects it does not
>>>>>
>>>>> FWIW, I'd suggest rephrasing as:
>>>>>
>>>>>   Because a @code{pure} function cannot have side effects
>>>>>
>>>>> because "can have no side-effects" can be read as
>>>>> "is allowed to have no side effects", which gave me pause
>>>>> when I read it the first time, and is the opposite of
>>>>> what you mean.
>>>>
>>>> That is what I meant: that const and pure functions are not allowed
>>>> to have any side-effects.  If they did, they could be unexpectedly
>>>> eliminated (i.e., the behavior is undefined when such a function
>>>> does have a side-effect).
>>>
>>> I know, but that's not what I read the first time (and found it
>>> odd so I had to re-read).  You can either assume that I'm the
>>> only one that will misunderstand it on first read, or you can
>>> swap a couple words and be sure no one will misunderstand it.
>>>
>>> Up to you.
>>
>> I'm chiming in a little late here, but I agree with Pedro that "can have
>> no side-effects" is confusing.  I'd say "cannot have side effects" or
>> "must have no side effects" instead.
> 
> There's nothing confusing about it.  It's an established phrase
> with millions of uses and only one meaning.  According to Google
> Books Ngram Viewer it's also more pervasive than either of
> the two suggested alternatives:
> 
>   http://goo.gl/FgXgwi

Sorry, but no.  The different phrases have slightly different
meanings.  The fact that one is used more often than than the other
does not imply that they have the same meaning, any more than this:

   http://goo.gl/U64uDZ

shows that people nowadays say "red" more often when then
mean "blue".

Compare:

 #1. The red pill can have no side effects.  (If you're lucky.  It's
     not guaranteed.  Buyer beware.)

 #2. The blue pill cannot have side effects.  (That's a guarantee.)

Those are different statements.  #1 implies possibility, while #2
leaves no margin for error.

When you say that "a pure function can have no side effects",
that can be reasonably read as

  a pure function may have no side effects if it chooses to,
  i.e., it's not required to have side effects.

But, a pure function _must_ have no side effects.  If a function has
side effects, then it no longer is a pure function, by definition.
That's what reads confusingly.

Your url actually proves the point.  Follow the url at the bottom
of that page:

 https://www.google.pt/search?q=%22can+have+no+effect%22&tbm=bks&lr=lang_en&gws_rd=cr&dcr=0&ei=NUPDWqqoPInxUqP8jPgN

And that leads to uses like:

 "In many cases, a treatment can have no effect or can have the effect"

 "the new grant can have no effect whatever, unless it have the effect"

etc., etc.

> 
>> Also note that non-hyphenated "side effects" seems to be preferred usage
>> as a noun phrase (at least it's the only form listed by m-w.com).
> 
> I'm all for using the preferred form.  I've made the change here
> and submitted a separate patch to remove the hyphen from the rest
> of the occurrences.
> 
> Attached is a changed patch that uses "cannot have side effects"
> instead of "can have no side effects."

Thank you.  LGTM, FWIW.

Pedro Alves

On 04/03/2018 03:27 AM, Pedro Alves wrote:
> On 04/02/2018 11:34 PM, Martin Sebor wrote:
>> On 04/02/2018 12:09 AM, Sandra Loosemore wrote:
>>> On 03/27/2018 03:21 PM, Pedro Alves wrote:
>>>> On 03/27/2018 09:19 PM, Martin Sebor wrote:
>>>>> On 03/27/2018 01:38 PM, Pedro Alves wrote:
>>>>>> On 03/27/2018 07:18 PM, Martin Sebor wrote:
>>>>>>> +Because a @code{pure} function can have no side-effects it does not
>>>>>>
>>>>>> FWIW, I'd suggest rephrasing as:
>>>>>>
>>>>>>   Because a @code{pure} function cannot have side effects
>>>>>>
>>>>>> because "can have no side-effects" can be read as
>>>>>> "is allowed to have no side effects", which gave me pause
>>>>>> when I read it the first time, and is the opposite of
>>>>>> what you mean.
>>>>>
>>>>> That is what I meant: that const and pure functions are not allowed
>>>>> to have any side-effects.  If they did, they could be unexpectedly
>>>>> eliminated (i.e., the behavior is undefined when such a function
>>>>> does have a side-effect).
>>>>
>>>> I know, but that's not what I read the first time (and found it
>>>> odd so I had to re-read).  You can either assume that I'm the
>>>> only one that will misunderstand it on first read, or you can
>>>> swap a couple words and be sure no one will misunderstand it.
>>>>
>>>> Up to you.
>>>
>>> I'm chiming in a little late here, but I agree with Pedro that "can have
>>> no side-effects" is confusing.  I'd say "cannot have side effects" or
>>> "must have no side effects" instead.
>>
>> There's nothing confusing about it.  It's an established phrase
>> with millions of uses and only one meaning.  According to Google
>> Books Ngram Viewer it's also more pervasive than either of
>> the two suggested alternatives:
>>
>>   http://goo.gl/FgXgwi
>
> Sorry, but no.

Sorry, but this is ridiculous.

I have no desire to debate this further.  (In case you find
it confusing, let me rephrase it: I do not have the desire
to debate this.)

Martin

On Mon, Apr 2, 2018 at 6:34 PM, Martin Sebor <msebor@gmail.com> wrote:
> Attached is a changed patch that uses "cannot have side effects"
> instead of "can have no side effects."

> +effects it does not make sense for such a function to return @code{void}.
> +Declaring such functions is diagnosed.

Let's make the last sentence singular ("such a function") as well.  OK
with that change in both hunks.

Jason