Subject: Re: bug#6018: 23.1.96; doc of version(-list)*

From: Eli Zaretskii <[email-masked]>
Date: Thu, 14 Jul 2011 02:30:56 -0400

> From: "Drew Adams" <[email-masked]>
> Cc: "'Lars Magne Ingebrigtsen'" <[email-masked]>,
>         "'Eli Zaretskii'" <[email-masked]>, <[email-masked]>
> Date: Wed, 13 Jul 2011 19:51:15 -0700
> 
> > Really? 
> > You have to be more specific about what's confusing you.
> 
> I was pretty darn specific about the non-specificity of this doc and what is
> missing.

You were bikeshedding, as usual.

> As I said:
> 
> > > The doc string of `version-regexp-alist' refers to the
> > > `version-list-*' functions, saying to consult their doc, so they
> > > cannot be said to be "internal".

That doc string no longer refers to anything but version-to-list.

And version-regexp-alist is itself an internal variable, so this is
not an evidence to the effect you want it to be.  The doc string of
version-regexp-alist is for developers of this group of functions, not
for users of their advertised APIs.

> > Examples are given, but no real explanation.  If the elements must be
> > integers, say so.  And say what a negative integer means.

Please explain where is the current doc string insufficient.  What you
did was express general consideration, not specific confusion points.
Please make a point of giving specific practical use cases where a doc
string leaves you in the dark regarding the outcome of a specific test
that uses the advertised API for Lisp programs.

> And as I said about `version-regexp-alist' and `version-to-list':
> 
> > again, there are only examples, no explanation.  Please
> > describe the _mapping_ between parts of version
> > strings (e.g. the sub regexps "pre", "beta", "alpha" etc.) 
> > and negative integers as list elements.

See above: unless you show a specific use case where this mapping
needs to be documented in the doc string, your arguments are nil and
void.

> And:
> 
> > Which regexps are mapped to negative integers?  Which of them
> > correspond to which negative integers? etc. (It's not
> > obvious that "pre" would follow "beta", for instance.) 

See above: why do you need that documented?  I submit you don't.

> > Also, we don't say what the "priority" means for 
> > version-regexp-alist.  What does it mean for a particular
> > alist entry to have a "priority" of -3?

Nothing of interest to you (unless you read the code, in which case it
should be obvious).  This is an implementation detail.

> And as I said about the `version* (non-list) functions:
> 
> > nothing is said about the comparison of strings with digits
> > other than zero. And that's arguably the most important and
> > most up for grabs.

You mean, it isn't obviously clear that 3 is greater than 2 and less
than 4?  It needs to be documented in a doc string?

> > And again, even for zeros and alpha strings, the 
> > "explanation" is only via examples. At least say something
> > about what kind of string comparison is done:
> > alphabetic for non-digits, describe the comparison of digit 
> > strings, mention case-insensitivity etc.

See above: give us a use case.  At least one.

> > Give users a clear understanding of just what the numeric 
> > ordering is that we use.
> 
> Enough details for you?

No, see above.  You wrote a lot, but all of it is irrelevant.

All the _real_ issues with these doc strings were taken care of, back
when you submitted this bug report.  All that's left is bikeshedding.

> That describes some of the interface/API info about these functions
> that is missing

You didn't show a single issue with the _advertised_ API that
indicates that some info is missing.

> and it includes some of the questions a user of these functions will
> have.

A user called Drew, perhaps.  Because he insists on having internal
functions and implementation details be documented as if they were
advertised APIs.