From: Eli Zaretskii <eliz@gnu.org>
To: "Drew Adams" <drew.adams@oracle.com>
Cc: cyd@stupidchicken.com, 6018@debbugs.gnu.org, larsi@gnus.org
Subject: bug#6018: 23.1.96; doc of version(-list)*
Date: Thu, 14 Jul 2011 02:30:56 -0400 [thread overview]
Message-ID: <E1QhFRo-0003ID-T5@fencepost.gnu.org> (raw)
In-Reply-To: <AA952B9484904DA2991CD725C2A4C16B@us.oracle.com> (drew.adams@oracle.com)
> 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.
next prev parent reply other threads:[~2011-07-14 6:30 UTC|newest]
Thread overview: 12+ messages / expand[flat|nested] mbox.gz Atom feed top
2010-04-23 19:04 bug#6018: 23.1.96; doc of version(-list)* Drew Adams
2010-04-23 20:39 ` Eli Zaretskii
2010-04-23 21:06 ` Drew Adams
2011-07-13 18:06 ` Lars Magne Ingebrigtsen
2011-07-13 18:20 ` Drew Adams
2011-07-14 2:04 ` Chong Yidong
2011-07-14 2:51 ` Drew Adams
2011-07-14 6:30 ` Eli Zaretskii [this message]
2011-07-14 14:05 ` Drew Adams
2011-07-14 15:58 ` Eli Zaretskii
2012-01-07 6:15 ` Lars Magne Ingebrigtsen
2011-07-16 18:42 ` Stefan Monnier
Reply instructions:
You may reply publicly to this message via plain-text email
using any one of the following methods:
* Save the following mbox file, import it into your mail client,
and reply-to-all from there: mbox
Avoid top-posting and favor interleaved quoting:
https://en.wikipedia.org/wiki/Posting_style#Interleaved_style
* Reply using the --to, --cc, and --in-reply-to
switches of git-send-email(1):
git send-email \
--in-reply-to=E1QhFRo-0003ID-T5@fencepost.gnu.org \
--to=eliz@gnu.org \
--cc=6018@debbugs.gnu.org \
--cc=cyd@stupidchicken.com \
--cc=drew.adams@oracle.com \
--cc=larsi@gnus.org \
/path/to/YOUR_REPLY
https://kernel.org/pub/software/scm/git/docs/git-send-email.html
* If your mail client supports setting the In-Reply-To header
via mailto: links, try the mailto: link
Be sure your reply has a Subject: header at the top and a blank line
before the message body.
Code repositories for project(s) associated with this external index
https://git.savannah.gnu.org/cgit/emacs.git
https://git.savannah.gnu.org/cgit/emacs/org-mode.git
This is an external index of several public inboxes,
see mirroring instructions on how to clone and mirror
all data and code used by this external index.