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: "Joseph S. Myers" <joseph at codesourcery dot com>
- To: Alexandre Oliva <aoliva at redhat dot com>
- Cc: Torvald Riegel <triegel at redhat dot com>, Carlos O'Donell <carlos at redhat dot com>, GNU C Library <libc-alpha at sourceware dot org>, Rich Felker <dalias at aerifal dot cx>
- Date: Mon, 25 Nov 2013 17:53:35 +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> <Pine dot LNX dot 4 dot 64 dot 1311201555320 dot 28804 at digraph dot polyomino dot org dot uk> <orli0itbm5 dot fsf at livre dot home> <Pine dot LNX dot 4 dot 64 dot 1311211322040 dot 14539 at digraph dot polyomino dot org dot uk> <or4n75t4b7 dot fsf at livre dot home> <Pine dot LNX dot 4 dot 64 dot 1311221324200 dot 5029 at digraph dot polyomino dot org dot uk> <orob5csdvx dot fsf at livre dot home> <Pine dot LNX dot 4 dot 64 dot 1311221535560 dot 8443 at digraph dot polyomino dot org dot uk> <or61rjs2li dot fsf at livre dot home>
On Sat, 23 Nov 2013, Alexandre Oliva wrote:
> Torvald values the annotations that justify (for internal consumers, not
> in the formatted manual) why a function is AS-Unsafe or AC-Unsafe, as I
> do. Using macros for them that expand to nothing is fine, but what
> about the documentation that currently defines them? Should it be
> removed altogether, or turned into comments?
I have no advice about that.
> > data-structures-inconsistent (except I'd think that is a sufficiently
> > fatal problem that the function should just be documented as
> > unconditionally AC-Unsafe
>
> The point is to document why it is unsafe.
The point of the documentation should be to make clear to users under what
circumstances (with the current implementation, or, better, under what
circumstances as an explicit choice about the API we wish to support) a
function may safely be used. If the answer is that the function should
never be used in AS or AC circumstances, then we don't need to say why in
the formatted manual, just that the answer is never.
> > (Again, this is in the AC-Unsafe context, so don't need to mention
> > asynchronous-cancellation in the keywords themselves.)
>
> The *definitions* of the keywords are not divided in sections, because
> some keywords apply to more than one section. Since there's a single
> namespace for the definitions, in cases in which the distinction is
> significant, it becomes necessary to have different keywords, and then
> I've resorted to bringing the context into the keyword name.
I think in these cases the definition of the keyword should describe what
it means in each context.
> Furthermore, if we're to link to the section that defines the macros,
> the @safety macro would need some way to tell that at least one of the
> keyword macros mentioned in arguments to its arguments expanded to a
> non-empty string in order to determine whether to expand the xref. I'm
> not sure this is possible in texinfo, and it doesn't make sense to add
> the xrefs manually if the macros themselves may come and go.
Definitions should always be linked to, simply to define the MT-Safe etc.
terms even if no keywords for more specific safety information are
present.
--
Joseph S. Myers
joseph@codesourcery.com
- References:
- Consensus on MT-, AS- and AC-Safety docs.
- Re: Consensus on MT-, AS- and AC-Safety docs.
- Re: Consensus on MT-, AS- and AC-Safety docs.
- Re: Consensus on MT-, AS- and AC-Safety docs.
- Re: Consensus on MT-, AS- and AC-Safety docs.
- Re: Consensus on MT-, AS- and AC-Safety docs.
- Re: Consensus on MT-, AS- and AC-Safety docs.
- Re: Consensus on MT-, AS- and AC-Safety docs.
- Re: Consensus on MT-, AS- and AC-Safety docs.
- Re: Consensus on MT-, AS- and AC-Safety docs.
- Re: Consensus on MT-, AS- and AC-Safety docs.