This is the mail archive of the
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: Alexandre Oliva <aoliva at redhat dot com>
- Cc: Carlos O'Donell <carlos at redhat dot com>, GNU C Library <libc-alpha at sourceware dot org>, Rich Felker <dalias at aerifal dot cx>, Torvald Riegel <triegel at redhat dot com>
- Date: Wed, 20 Nov 2013 16:03:24 +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> <Pine dot LNX dot 4 dot 64 dot 1311182312130 dot 8831 at digraph dot polyomino dot org dot uk> <orob5fv8nl dot fsf at livre dot home>
On Wed, 20 Nov 2013, Alexandre Oliva wrote:
> On Nov 18, 2013, "Joseph S. Myers" <email@example.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