[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index]
Re: documentation structure (was: attribute: add comments)
From: |
Paul Eggert |
Subject: |
Re: documentation structure (was: attribute: add comments) |
Date: |
Sun, 10 May 2020 11:56:29 -0700 |
User-agent: |
Mozilla/5.0 (X11; Linux x86_64; rv:68.0) Gecko/20100101 Thunderbird/68.7.0 |
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.