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: "Carlos O'Donell" <carlos at redhat dot com>
- To: "Joseph S. Myers" <joseph at codesourcery 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: Tue, 19 Nov 2013 12:41:46 -0500
- Subject: Re: Consensus on MT-, AS- and AC-Safety docs.
- Authentication-results: sourceware.org; auth=none
- References: <528A7C8F dot 8060805 at redhat dot com> <Pine dot LNX dot 4 dot 64 dot 1311182312130 dot 8831 at digraph dot polyomino dot org dot uk>
On 11/18/2013 06:21 PM, Joseph S. Myers wrote:
> 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).
Regarding the documenting of a bug for which a patch exists, that is
now in Alex's court to remove the documentation for that since you've
just checked in your patch for powerpc-nofpu floating point state
after Adhemerval's (IBM) review.
You make a very good point about confusing users, and I have no
objections to expanding the text to read something that is very clear
that these comments for now are not what we intend (given that this
is our first pass over the functions).
Cheers,
Carlos.