GNU bug report logs - #5744
23.1.92; doc string of `version<' etc.

Previous Next

Full log

View this message in rfc822 format

From: "Drew Adams" <drew.adams <at> oracle.com>
To: "'Štepán Nemec'" <stepnem <at> gmail.com>
Cc: 5744 <at> debbugs.gnu.org
Subject: bug#5744: 23.1.92; doc string of `version<' etc.
Date: Sat, 20 Mar 2010 11:10:10 -0700

> > 1. Change "lesser than" to "less than".
>
> "Lesser" seems completely fine to me, but I'm not a native speaker.

That's why it seems completely fine to you. It's not English. ;-)
"less than" is correct; "lesser than" is not correct.

> > 2. Say explicitly that V1 and V2 are strings.
>
> I think that's clear from the docstring, but more clarity
> never hurts, yes.
>
> > Say in fact that they are strings of the format returned by variable
> > `emacs-version'.
>
> That would be misleading at best IMHO.
> The function accepts a far wider set of arguments.

Oh really? Then all the more reason to explicitly specify the accepted formats
(completely).
You cannot use a function reliably if you don't know what kinds of arguments it
handles.

> Also note that you would most probably want to change docstrings of
> the whole family of the version functions to stay consistent.

Of course. That's why I wrote "`version<' ETC." in the subject line.


Also:

3. Specifically state the ordering rule. Wrt alphabetical comparison, don't just
give an example, state that letters are compared alphabetically (and state
whether that's case-sensitive).

4. Mention at least one of these version-comparison functions in the Elisp
manual, node `Version Info'.

Previous Next

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