This is the mail archive of the
libc-alpha@sourceware.org
mailing list for the glibc project.
Re: [PATCH 3/3] manual: Add new header and standards annotations.
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