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

[Paul Eggert]

On 5/10/20 10:20 AM, Bruno Haible wrote:

> Let me try to reinstante the answer to 1. "Why, when", by grouping the macros
> according to their use-case.

Sure, that's OK. Some quibbles, though.

The distinction between compiler diagnostics and the other sections is somewhat
confusing. ATTRIBUTE_NONNULL is not merely about compiler diagnostics; it's also
about optimization. Similarly for ATTRIBUTE_RETURNS_NONNULL (which I think was
primarily motivated by optimization). Conversely, ATTRIBUTE_PURE,
ATTRIBUTE_CONST and ATTRIBUTE_LEAF are about diagnostics as well as being about
optimization. So it may make sense to merge or at least cross-reference the two
sections.

The section "Attributes for specific kinds of functions" is only about compiler
diagnostics, so perhaps it should be a subsection of the compiler-diagnostics
section, with the compiler-diagnostics macros that are about functions moved to
this subsection.

I would replace "Attributes that make invalid code valid" to "Attributes for
extensions to C".

These are all minor quibbles; the current version's fine.