GNU bug report logs - #9493
24.0.50; doc string of `read-from-string'

Previous Next

To add a comment to this bug, you must first unarchive it, by sending
a message to control AT debbugs.gnu.org, with unarchive 9493 in the body.
You can then email your comments to 9493 AT debbugs.gnu.org in the normal way.

Toggle the display of automated, internal messages from the tracker.

Message #5 received at submit <at> debbugs.gnu.org (full text, mbox):

From: "Drew Adams" <drew.adams <at> oracle.com>
To: <bug-gnu-emacs <at> gnu.org>
Subject: 24.0.50; doc string of `read-from-string'
Date: Tue, 13 Sep 2011 09:18:39 -0700

The return value of this function is the most important info that can be
conveyed by its doc string.  All that is said is that the value returned
is "a cons: (OBJECT-READ . FINAL-STRING-INDEX)".  There is no
description of either OBJECT-READ (could be guessed, but better to
specify it) or, especially, FINAL-STRING-INDEX (not obvious at all).
 
Describe these properly, as is done in the Elisp manual.  It is not long
to say what the manual says for FINAL-STRING-INDEX: "an integer giving
the position of the next remaining character in the string (i.e., the
first one not read)."  It would be enough to say this: "zero-based
position of first char not read".
 

In GNU Emacs 24.0.50.1 (i386-mingw-nt5.1.2600)
 of 2011-09-05 on 3249CTO
Windowing system distributor `Microsoft Corp.', version 5.1.2600
configured using `configure --with-gcc (4.5) --no-opt'
 

Message #8 received at 9493 <at> debbugs.gnu.org (full text, mbox):

From: Lars Magne Ingebrigtsen <larsi <at> gnus.org>
To: "Drew Adams" <drew.adams <at> oracle.com>
Cc: 9493 <at> debbugs.gnu.org
Subject: Re: 24.0.50; doc string of `read-from-string'
Date: Mon, 19 Sep 2011 10:27:49 +0200

"Drew Adams" <drew.adams <at> oracle.com> writes:

> The return value of this function is the most important info that can be
> conveyed by its doc string.  All that is said is that the value returned
> is "a cons: (OBJECT-READ . FINAL-STRING-INDEX)".  There is no
> description of either OBJECT-READ (could be guessed, but better to
> specify it) or, especially, FINAL-STRING-INDEX (not obvious at all).
>
> Describe these properly, as is done in the Elisp manual.  It is not long
> to say what the manual says for FINAL-STRING-INDEX: "an integer giving
> the position of the next remaining character in the string (i.e., the
> first one not read)."  It would be enough to say this: "zero-based
> position of first char not read".

I've now documented FINAL-STRING-INDEX.  Saying "OBJECT-READ is the
object read" seems superfluous.

-- 
(domestic pets only, the antidote for overdose, milk.)
  bloggy blog http://lars.ingebrigtsen.no/

Previous Next

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