GNU bug report logs - #15632
24.3.50; doc string of `replace-match-maybe-edit'

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 15632 in the body.
You can then email your comments to 15632 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.3.50; doc string of `replace-match-maybe-edit'
Date: Wed, 16 Oct 2013 08:48:11 -0700 (PDT)

1. It is not true that NEWTEXT is "just passed on".  If `\?' is present
then it is updated to the result of editing.  It is that possibly edited
result that is then passed to `replace-match'.


2. Even though the first line suggests that this function will use
`replace-match' as a helper, this part of the doc string is unclear (and
false - see #1):

  "NEWTEXT, FIXEDCASE, LITERAL are just passed on."

The point of saying that an arg is "passed on" is to refer the reader to
the function where it is actually used and documented.  Rather than
documenting here what the parameter does, we send you to the doc of
another function, where the parameter is described fully.

The text should say something like this:

  "FIXEDCASE, LITERAL are passed to `replace-match' (which see).  After
  possibly editing it, NEWTEXT is also passed to `replace-match'.


3. The next-to-last sentence is unclear.  NOEDIT is *always* "passed
in".  The doc should say that the return value is nil iff NOEDIT is nil
or NEWTEXT was edited.



In GNU Emacs 24.3.50.1 (i686-pc-mingw32)
 of 2013-10-09 on LEG570
Bzr revision: 114596 jan.h.d <at> swipnet.se-20131009185014-vynfyw4o8p5fge54
Windowing system distributor `Microsoft Corp.', version 6.1.7601
Configured using:
 `configure --enable-checking 'CFLAGS=-O0 -g3' CPPFLAGS=-DGLYPH_DEBUG=1'

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

From: Lars Ingebrigtsen <larsi <at> gnus.org>
To: Drew Adams <drew.adams <at> oracle.com>
Cc: 15632 <at> debbugs.gnu.org
Subject: Re: bug#15632: 24.3.50; doc string of `replace-match-maybe-edit'
Date: Fri, 07 Feb 2014 19:55:55 -0800

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

> 1. It is not true that NEWTEXT is "just passed on".  If `\?' is present
> then it is updated to the result of editing.  It is that possibly edited
> result that is then passed to `replace-match'.
>
> 2. Even though the first line suggests that this function will use
> `replace-match' as a helper, this part of the doc string is unclear (and
> false - see #1):
>
>   "NEWTEXT, FIXEDCASE, LITERAL are just passed on."
>
> The point of saying that an arg is "passed on" is to refer the reader to
> the function where it is actually used and documented.  Rather than
> documenting here what the parameter does, we send you to the doc of
> another function, where the parameter is described fully.
>
> The text should say something like this:
>
>   "FIXEDCASE, LITERAL are passed to `replace-match' (which see).  After
>   possibly editing it, NEWTEXT is also passed to `replace-match'.

Fixed on trunk.

> 3. The next-to-last sentence is unclear.  NOEDIT is *always* "passed
> in".  The doc should say that the return value is nil iff NOEDIT is nil
> or NEWTEXT was edited.

This seems to have been edited already.

-- 
(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.