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/