This is the mail archive of the libc-alpha@sourceware.org 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 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


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