GNU bug report logs - #6018
23.1.96; doc of version(-list)*

Previous Next

Full log

View this message in rfc822 format

From: Eli Zaretskii <eliz <at> gnu.org>
To: "Drew Adams" <drew.adams <at> oracle.com>
Cc: cyd <at> stupidchicken.com, 6018 <at> debbugs.gnu.org, larsi <at> gnus.org
Subject: bug#6018: 23.1.96; doc of version(-list)*
Date: Thu, 14 Jul 2011 02:30:56 -0400

> From: "Drew Adams" <drew.adams <at> oracle.com>
> Cc: "'Lars Magne Ingebrigtsen'" <larsi <at> gnus.org>,
>         "'Eli Zaretskii'" <eliz <at> gnu.org>, <6018 <at> debbugs.gnu.org>
> 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.

Previous Next

GNU bug tracking system
Copyright (C) 1999 Darren O. Benham, 1997,2003 nCipher Corporation Ltd, 1994-97 Ian Jackson.