This is the mail archive of the mailing list for the glibc project.

Index Nav: [Date Index] [Subject Index] [Author Index] [Thread Index]
Message Nav: [Date Prev] [Date Next] [Thread Prev] [Thread Next]
Other format: [Raw text]

Re: Consensus on MT-, AS- and AC-Safety docs.

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).


Index Nav: [Date Index] [Subject Index] [Author Index] [Thread Index]
Message Nav: [Date Prev] [Date Next] [Thread Prev] [Thread Next]