This is the mail archive of the
libc-alpha@sourceware.org
mailing list for the glibc project.
Re: Consensus on MT-, AS- and AC-Safety docs.
- From: "Joseph S. Myers" <joseph at codesourcery dot com>
- To: Carlos O'Donell <carlos at redhat dot com>
- Cc: GNU C Library <libc-alpha at sourceware dot org>, Rich Felker <dalias at aerifal dot cx>, Torvald Riegel <triegel at redhat dot com>, Alexandre Oliva <aoliva at redhat dot com>
- Date: Mon, 18 Nov 2013 23:21:44 +0000
- Subject: Re: Consensus on MT-, AS- and AC-Safety docs.
- Authentication-results: sourceware.org; auth=none
- References: <528A7C8F dot 8060805 at redhat dot com>
On Mon, 18 Nov 2013, Carlos O'Donell wrote:
> Having said all this, do any of you object in any way to the
> addition of this documentation?
My main concern is not that this documents a bug for which a patch exists
(although I think it's a mistake to put in a patch that should be about to
be reverted) - rather, it's that it is insufficiently clear at the sites
where the safety properties are documented that they are only observed
properties of the current implementation and not necessarily part of the
glibc API - as far as I can see, someone going straight to the
documentation for a function would miss the carefully explained caveats.
I would rather the macros expanded to something that explicitly said
"Current implementation safety properties (not necessarily intended
interface):" - and then there could be a separate @apisafety (for example)
macro used in cases where we believe from a review that the properties are
those we intend for the glibc API (or @apisafety could be used with
caveats about how the current implementation fails to meet the intent,
with a comment about the relevant bug in Bugzilla, if appropriate).
--
Joseph S. Myers
joseph@codesourcery.com