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 Sat, 2013-11-23 at 10:51 -0200, Alexandre Oliva wrote:
> On Nov 22, 2013, "Joseph S. Myers" <joseph@codesourcery.com> wrote:
> 
> > On Fri, 22 Nov 2013, Alexandre Oliva wrote:
> >> >> If keywords make sense on their own, readers won't look up their
> >> >> detailed definitions, and miss out on the details you regard as
> >> >> essential for them to be aware of.
> >> 
> >> > I'd like extended names, which are links to their definitions.
> >> 
> >> Do you acknowledge that this will not get users to follow the links so
> >> as to look at the precise definitions?
> 
> > For conscientious readers, we need to include the link to make it easy for 
> > them to look up the documentation.
> 
> âNeed toâ is too strong; it's surely convenient.  But there are some
> texinfo macro challenges to solve to make this work; more on that below.
> 
> > For unconscientious readers, there's only so much we can do.
> 
> Well, there is: we could use terms that do *not* immediately suggest an
> interpretation that might be incomplete or wrong, so that they'd have no
> choice but to actually look it up if they want to know what it means.

I agree that people might be likely to misinterpret names if the names
are too easily associated with some semantics by many people.  But an
cryptic name (eg, a made-up name) won't prevent that.  For example, I
guess that many people would remember what "MT-Safety" means by
associating some concept of (multi-)thread safety; at which point they
are as likely to have a different understanding of the semantics as if
you had called it "(Multi-)Thread Safety" in the first place.  Likewise
with "envromt", if people would associate this name with "environment"
anyway (like I would certainly do, for example).

> But, well, since it's not the first time I make this point and you
> dismiss it,, you clearly don't want to induce people to look up and read
> the details whose inclusion you asked for and argued it was important
> for them to know.

I don't think this is the point.  To me, introducing artificial words
just doesn't help, because I wouldn't want to remember them anyway.
What I would want is an easy to remember term that is not some gibberish
(ie, where I have to remember a new word that doesn't even follow the
schemes that other words in the language are built on); second, this
term should be easy to associate with the full definition.  That's
certainly just my opinion, but neither of us here knows a lot about
cognitive psychology or the like I believe, so I guess we need to rely
us as a sample set here.

Given that the definition is likely complex, it will never be an
equivalent of the definition anyway; but that's fine, and I think fairly
easy to remember unless we don't make the names we choose similar to
names that are already used often in this area.  (For example,
"(Multi-)Thread Safety" is already overloaded with many imprecise
different "definitions", I believe; but I don't know of any competing
set of constraints to our MT-Safety, so there's nothing that I could
misinterpret it for...)

> >> -- Function: void setpwent (void)
> >> | MT-Unsafe uses-a-static-buffer-overwritten-by-other-calls,
> 
> > static-buffer (there's no need to make them complete phrases as long as 
> > the words are complete words or well-established abbreviations, but they 
> > shouldn't be glibc-specific abbreviations or run multiple words together 
> > with possible overlap).
> 
> So far the only argument I've seen to support the requirements above is
> âI like it better this wayâ, without any regard or even acknowledgement
> to the functional advantage of the opposite.

I've explained why I disagree with the functional advantage you see, and
why I prefer static-buffer over the made-up words, for example.  See my
previous email, and above.

> Considering that such complete words with well-known meanings risk being
> far more misleading than helpful, because they only bring a small part
> of the problem to mind, I'm still not convinced that's the way to go.

The definition will be complex, so it will always be just a way to
associate the full concept / definition of the constraint.  The context
is our constraints to MT-Safety, so a user would have to choose only in
this context; thus, as long as it's a way to mentally pick the right
item in the set of constraints, why shouldn't that work?

> I'll say that the ones you proposed do not *look* so awful as did the
> ridiculously long ones I proposed so as to satisfy the requirements you
> posted at first.  However, now that you've shown you're willing to
> sacrifice precision to get brevity back, I must ask why not have both.

I think there's a difference between brevity in the number of characters
the name needs, and brevity in the number of "brain slots" this needs.
"envromt" is shorter than "environment" in characters, but harder to
deal with because it's a new, special sequence of characters.  If you
deal with "envromt" every day, you might want to remember the new word
(and the "read-only" origin of it), and it might just be the right thing
to do.  But if that name is just one of the many things you need to deal
with (which holds for many of our users, I believe), then that the new
name is just mental overhead because it's one more odd thing you have to
remember.

> > Documenting limitations of safety only makes sense if we wish to support 
> > use of the function in a particular context provided the user follows 
> > particular rules.  In this case, and probably many cases for AS-Safety, I 
> > think we should just say AS-Unsafe - we don't want to support this in 
> > signal handlers at all, under any circumstances, and so don't need to 
> > document anything about what makes it unsafe, just that it is unsafe.
> 
> 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?

What about keeping them around as "examples" why a certain thing could
be MT-Unsafe, for example?  But keeping them as comments would be fine
too IMHO.


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