[PATCH 3/3] manual: Add new header and standards annotations.

[Joseph Myers]

On Fri, 25 Nov 2016, Joseph Myers wrote:

> I don't think you should document feature test macros (certainly not 
> without a very careful review that the conditionals actually make sense).  

To give more rationale here:

Documentation should be for stable interfaces, not for implementation 
details.  The fact that something is part of a given standard is a stable 
interface.  The fact that something is declared under certain conditions 
may not be a stable interface, if for example it's an implementation 
detail that header X includes header Y (where the standards permit but 
don't require this) or defines type foo_t rather than using __foo_t.  
Effectively, the API to document for a header is a subset of what it 
actually exposes at any given time.  (Every public symbol should be 
documented somewhere in the manual, but not necessarily for every header 
or feature test macro that actually exposes that symbol.)

-- 
Joseph S. Myers
joseph@codesourcery.com