From: Joseph Myers <joseph@codesourcery.com>
To: Rical Jasan <ricaljasan@pacific.net>
Cc: <libc-alpha@sourceware.org>,
Michael Kerrisk <mtk.manpages@gmail.com>,
Carlos O'Donell <carlos@redhat.com>
Subject: Re: [PATCH 3/3] manual: Add new header and standards annotations.
Date: Fri, 25 Nov 2016 15:09:00 -0000 [thread overview]
Message-ID: <alpine.DEB.2.20.1611251503410.28633@digraph.polyomino.org.uk> (raw)
In-Reply-To: <alpine.DEB.2.20.1611251425271.28633@digraph.polyomino.org.uk>
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
next prev parent reply other threads:[~2016-11-25 15:09 UTC|newest]
Thread overview: 32+ messages / expand[flat|nested] mbox.gz Atom feed top
2016-11-23 6:38 [PATCH 0/3] manual: Header & Standards Cleanup Rical Jasan
2016-11-23 6:38 ` [PATCH 3/3] manual: Add new header and standards annotations Rical Jasan
2016-11-23 17:42 ` Joseph Myers
2016-11-24 10:22 ` Rical Jasan
2016-11-24 13:37 ` Joseph Myers
2016-11-25 5:59 ` Rical Jasan
2016-11-25 14:53 ` Joseph Myers
2016-11-25 15:09 ` Joseph Myers [this message]
2016-11-30 10:39 ` Rical Jasan
2016-11-30 10:45 ` Florian Weimer
2016-11-30 12:50 ` Joseph Myers
2016-12-02 11:54 ` Rical Jasan
2016-12-02 13:56 ` Joseph Myers
2016-12-05 7:59 ` Rical Jasan
2016-11-30 12:38 ` Joseph Myers
2016-12-05 5:33 ` Rical Jasan
2016-12-05 18:22 ` Joseph Myers
2016-12-06 10:57 ` Rical Jasan
2016-12-06 15:59 ` Joseph Myers
2016-12-06 16:36 ` Zack Weinberg
2016-11-25 7:36 ` Rical Jasan
2016-11-25 16:17 ` Joseph Myers
2016-11-30 10:46 ` Rical Jasan
2016-11-30 12:52 ` Joseph Myers
2016-11-23 6:38 ` [PATCH 1/3] manual: Refactor " Rical Jasan
2016-11-23 17:31 ` Joseph Myers
2016-11-24 9:34 ` Rical Jasan
2016-11-24 13:17 ` Joseph Myers
2016-11-25 3:44 ` Rical Jasan
2016-11-25 14:25 ` Joseph Myers
2016-11-30 8:58 ` Rical Jasan
2016-11-23 6:38 ` [PATCH 2/3] manual: Convert @tables of variables to @vtables Rical Jasan
Reply instructions:
You may reply publicly to this message via plain-text email
using any one of the following methods:
* Save the following mbox file, import it into your mail client,
and reply-to-all from there: mbox
Avoid top-posting and favor interleaved quoting:
https://en.wikipedia.org/wiki/Posting_style#Interleaved_style
* Reply using the --to, --cc, and --in-reply-to
switches of git-send-email(1):
git send-email \
--in-reply-to=alpine.DEB.2.20.1611251503410.28633@digraph.polyomino.org.uk \
--to=joseph@codesourcery.com \
--cc=carlos@redhat.com \
--cc=libc-alpha@sourceware.org \
--cc=mtk.manpages@gmail.com \
--cc=ricaljasan@pacific.net \
/path/to/YOUR_REPLY
https://kernel.org/pub/software/scm/git/docs/git-send-email.html
* If your mail client supports setting the In-Reply-To header
via mailto: links, try the mailto: link
Be sure your reply has a Subject: header at the top and a blank line
before the message body.
This is a public inbox, see mirroring instructions
for how to clone and mirror all data and code used for this inbox;
as well as URLs for read-only IMAP folder(s) and NNTP newsgroup(s).