Re: documentation structure (was: attribute: add comments)

[Paul Eggert]

On 5/10/20 1:24 PM, Bruno Haible wrote:

> I view ATTRIBUTE_PURE, ATTRIBUTE_CONST as mainly an optimization hint. They
> produce diagnostics only if the attribute has been misplaced, or you can let
> the compiler suggest to you where these attribute would make sense. But what
> would be the diagnostics that are useful to the developer, independently of
> optimization?

Some developers - even in C - prefer a more functional style of programming, and
these attributes are useful cues to the reader that the function lacks side
effects etc. To developers in this category, knowing whether a function is pure
or const can be more important than optimization.

> And for ATTRIBUTE_LEAF, I cannot imagine any useful diagnostics at all

I goofed; I shouldn't have added that to the list. There are a few useful
diagnostics (if a function has aliases, one should be a leaf if the other is)
but they don't come up much.

>> The section "Attributes for specific kinds of functions" is only about 
>> compiler
>> diagnostics
> 
> True. But it is about kinds of functions that are so rare (probably less than 
> 2%
> of all functions). The intent of having it in a separate section is that the
> reader can rapidly skip this section when it's not interesting to them.

Fine, but ATTRIBUTE_FORMAT etc. also apply only to a few functions, no?
> the reader would be a "standards lawyer" (familiar with the way standards
> are usually written) in order to understand what you mean by "extensions to 
> C".

Fair enough.

> Similarly, when I had wording regarding "side effects" and you replaced it
> with "observable state": I think "observable state" is a term from the
> standards, but ask a computer science junior what "observable state" is?
> I bet the term "side effects" is generally more understood.

Using "observable state" makes it easier to document the distinction between
ATTRIBUTE_CONST and ATTRIBUTE_PURE, something that has tripped me up more than
once.  I stole the term "observable state" from the GCC manual and I imagine it
uses the term for the same reason.