Re: emacs-26 aecbbd5: * src/fns.c (Fmapconcat): Doc fix. (Bug#35710)

Re: emacs-26 aecbbd5: * src/fns.c (Fmapconcat): Doc fix. (Bug#35710)

[Robert Pluim]

>>>>> On Fri,  7 Jun 2019 09:00:42 -0400 (EDT), eliz@gnu.org (Eli Zaretskii) said:
    Eli> diff --git a/src/fns.c b/src/fns.c
    Eli> index 8db2a86..2276a99 100644
    Eli> --- a/src/fns.c
    Eli> +++ b/src/fns.c
    Eli> @@ -2494,8 +2494,12 @@ mapcar1 (EMACS_INT leni, Lisp_Object *vals, Lisp_Object fn, Lisp_Object seq)
    Eli>  DEFUN ("mapconcat", Fmapconcat, Smapconcat, 3, 3, 0,
    Eli>         doc: /* Apply FUNCTION to each element of SEQUENCE, and concat the results as strings.
    Eli>  In between each pair of results, stick in SEPARATOR.  Thus, " " as
    Eli> -SEPARATOR results in spaces between the values returned by FUNCTION.
    Eli> -SEQUENCE may be a list, a vector, a bool-vector, or a string.  */)
    Eli> +  SEPARATOR results in spaces between the values returned by FUNCTION.
    Eli> +SEQUENCE may be a list, a vector, a bool-vector, or a string.
    Eli> +SEPARATOR must be a string.
    Eli> +FUNCTION must be a function of one argument, and must return a value
    Eli> +  that is a sequence of characters: either a string, or a vector or
    Eli> +  list of numbers that are valid character codepoints.  */)
    Eli>    (Lisp_Object function, Lisp_Object sequence, Lisp_Object separator)

Eli, those whitespace changes look a little suspicious to me, they
result in a docstring like this:

    Apply FUNCTION to each element of SEQUENCE, and concat the results as strings.
    In between each pair of results, stick in SEPARATOR.  Thus, " " as
      SEPARATOR results in spaces between the values returned by FUNCTION.
    SEQUENCE may be a list, a vector, a bool-vector, or a string.
    SEPARATOR must be a string.
    FUNCTION must be a function of one argument, and must return a value
      that is a sequence of characters: either a string, or a vector or
      list of numbers that are valid character codepoints.

Robert

Re: emacs-26 aecbbd5: * src/fns.c (Fmapconcat): Doc fix. (Bug#35710)

[Juanma Barranquero]

On Mon, Jun 10, 2019 at 12:28 PM Robert Pluim <rpluim@gmail.com> wrote:

> Eli, those whitespace changes look a little suspicious to me, they
> result in a docstring like this:

That indentation style helps in visually separating consecutive
arguments or values, etc. when their descriptions are long. It's
occasionally used on the sources.

Re: emacs-26 aecbbd5: * src/fns.c (Fmapconcat): Doc fix. (Bug#35710)

[Robert Pluim]

>>>>> On Mon, 10 Jun 2019 15:46:34 +0200, Juanma Barranquero <lekktu@gmail.com> said:

    Juanma> On Mon, Jun 10, 2019 at 12:28 PM Robert Pluim <rpluim@gmail.com> wrote:
    >> Eli, those whitespace changes look a little suspicious to me, they
    >> result in a docstring like this:

    Juanma> That indentation style helps in visually separating consecutive
    Juanma> arguments or values, etc. when their descriptions are long. It's
    Juanma> occasionally used on the sources.

OK, I donʼt recall ever seeing it before.

Robert

Re: emacs-26 aecbbd5: * src/fns.c (Fmapconcat): Doc fix. (Bug#35710)

[Eli Zaretskii]

> From: Robert Pluim <rpluim@gmail.com>
> Cc: Eli Zaretskii <eliz@gnu.org>
> Date: Mon, 10 Jun 2019 12:27:15 +0200
> 
> Eli, those whitespace changes look a little suspicious to me, they
> result in a docstring like this:
> 
>     Apply FUNCTION to each element of SEQUENCE, and concat the results as strings.
>     In between each pair of results, stick in SEPARATOR.  Thus, " " as
>       SEPARATOR results in spaces between the values returned by FUNCTION.
>     SEQUENCE may be a list, a vector, a bool-vector, or a string.
>     SEPARATOR must be a string.
>     FUNCTION must be a function of one argument, and must return a value
>       that is a sequence of characters: either a string, or a vector or
>       list of numbers that are valid character codepoints.

Why is this suspicious?  Text has been indented to allow easily
finding the beginning of the description of each argument.  We do that
in many other places.