[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index]
Re: master 583cb26 2/3: Improve accuracy in string-replace description (
From: |
Robert Pluim |
Subject: |
Re: master 583cb26 2/3: Improve accuracy in string-replace description (bug#43598) |
Date: |
Mon, 28 Sep 2020 13:09:27 +0200 |
>>>>> 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
--
- Re: master 583cb26 2/3: Improve accuracy in string-replace description (bug#43598), Robert Pluim, 2020/09/28
- Re: master 583cb26 2/3: Improve accuracy in string-replace description (bug#43598), Mattias Engdegård, 2020/09/28
- Re: master 583cb26 2/3: Improve accuracy in string-replace description (bug#43598),
Robert Pluim <=
- Message not available
- Re: master 583cb26 2/3: Improve accuracy in string-replace description (bug#43598), Robert Pluim, 2020/09/28
- Re: master 583cb26 2/3: Improve accuracy in string-replace description (bug#43598), John Yates, 2020/09/28
- RE: master 583cb26 2/3: Improve accuracy in string-replace description (bug#43598), Drew Adams, 2020/09/28
- Re: master 583cb26 2/3: Improve accuracy in string-replace description (bug#43598), Eli Zaretskii, 2020/09/28
- RE: master 583cb26 2/3: Improve accuracy in string-replace description (bug#43598), Drew Adams, 2020/09/28
- Re: master 583cb26 2/3: Improve accuracy in string-replace description (bug#43598), Eli Zaretskii, 2020/09/28
- Re: master 583cb26 2/3: Improve accuracy in string-replace description (bug#43598), John Yates, 2020/09/28
- RE: master 583cb26 2/3: Improve accuracy in string-replace description (bug#43598), Drew Adams, 2020/09/28
- Re: master 583cb26 2/3: Improve accuracy in string-replace description (bug#43598), Eli Zaretskii, 2020/09/28
- RE: master 583cb26 2/3: Improve accuracy in string-replace description (bug#43598), Drew Adams, 2020/09/29