bug#15632: 24.3.50; doc string of `replace-match-maybe-edit'

bug#15632: 24.3.50; doc string of `replace-match-maybe-edit'

[Drew Adams]

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@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'

bug#15632: 24.3.50; doc string of `replace-match-maybe-edit'

[Lars Ingebrigtsen]

Drew Adams <drew.adams@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/