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

["Joseph S. Myers" <joseph at codesourcery dot com>]

On Wed, 20 Nov 2013, Alexandre Oliva wrote:

> On Nov 18, 2013, "Joseph S. Myers" <joseph@codesourcery.com> wrote:
> 
> > 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'm a bit confused by the statement above.
> 
> The latter part talks about the notes attached to individual functions,
> whereas the first part seems to be talking about the definitions of the
> properties in intro.texi.  The definitions are preceded by this caveat:

The normal state of documentation in the glibc manual should be that what 
it documents is always the API that glibc intends to support even when the 
implementation changes.  Thus:

* Any documentation deviating from this needs to make very clear that it 
is not normal documentation, but something else.

* The case that it concise should be documentation of safety properties 
that reflect intention *and* are believed to be followed by the current 
implementation.  The exceptional cases, where the documentation is an 
interim description of the current code rather than of intention, or 
where the current code is known to deviate from intention, need extra 
wording to make clear that they are exceptions.

(I'd also say that the stable API case should be the case that's concise 
in the Texinfo source as well as in the formatted manual - say @safety for 
stable API cases, @currentimplementationsafety for observed properties of 
the current implementation that may not reflect intent.)

>   Although we strive to abide by the standards, in some cases our
>   implementation is safe even when the standard does not demand safety,
>   and in other cases our implementation does not meet the standard
>   safety requirements.  At this point, we document the result of an
>   assessment of the properties of our implementation, so the safety
>   documentation in this manual is not to be regarded as a promise of
>   future behavior: in future releases, functions that are documented as
>   safe may become unsafe, and safety constraints may be removed or
>   introduced.  We envision turning the results of the assessment into a
>   set of promises as stable as our interfaces, but we are not there yet.
> 
> which would presumably alleviate your concerns.  As for the latter

Only when a sufficent part of that is present at the sites of individual 
function documentation, so that someone doing "info <function>" sees the 
prominent note about how the documentation is something different from 
normal documentation of a stable API.

-- 
Joseph S. Myers
joseph@codesourcery.com