Re: master 583cb26 2/3: Improve accuracy in string-replace description (bug#43598)

[Robert Pluim <rpluim@gmail.com>]

>>>>> On Mon, 28 Sep 2020 11:59:43 +0200, Mattias Engdegård <mattiase@acm.org> said:

    Mattias> 28 sep. 2020 kl. 11.42 skrev Robert Pluim <rpluim@gmail.com>:
    Mattias> @defun string-replace fromstring tostring instring
    Mattias> -This function copies @var{instring} and replaces any occurrences of
    Mattias> -@var{fromstring} with @var{tostring}.
    Mattias> +This function returns a string equal to @var{instring} where any
    Mattias> +occurrences of @var{fromstring} have been replaced with
    Mattias> +@var{tostring}.  It may return one of its arguments.
    Mattias> +Case is significant, and text properties are ignored.
    Mattias> @end defun
    >> 
    >> 'equal'? Really? And itʼs kind of passive-voicey.

    Mattias> Thank you for scrutinising my changes!

    Mattias> For technical documentation, a declarative or functional style is
    Mattias> often appropriate than a procedural one. We would prefer defining (+ A
    Mattias> B) as the sum of A and B instead of saying that it takes A, then adds
    Mattias> B, and finally returns the result.

OK, but in this case the 'have been replaced' is less direct than it
could be.

    >> How about:
    >> 
    >> This function replaces any occurences of @var{fromstring} with
    >> @var{tostring} in @var{instring} and returns the result.

    Mattias> That is probably fine. I wanted there to be no reason to
    Mattias> misread it as a mutation of INSTRING, but the risk is
    Mattias> probably minimal. I'll amend the text.

Emacs documentation spoils me: destructive modification is called out
explicitly when it can happen, which means I assume that if itʼs not
mentioned, it canʼt happen.

Robert
--