[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index]
bug#6018: 23.1.96; doc of version(-list)*
From: |
Eli Zaretskii |
Subject: |
bug#6018: 23.1.96; doc of version(-list)* |
Date: |
Thu, 14 Jul 2011 02:30:56 -0400 |
> From: "Drew Adams" <drew.adams@oracle.com>
> Cc: "'Lars Magne Ingebrigtsen'" <larsi@gnus.org>,
> "'Eli Zaretskii'" <eliz@gnu.org>, <6018@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.
bug#6018: 23.1.96; doc of version(-list)*, Stefan Monnier, 2011/07/16