Re: list, set, oset, map, omap: avoid imperative voice in documentation

[Jim Meyering]

On Sun, Feb 2, 2020 at 4:17 AM Bruno Haible <address@hidden> wrote:
> Each time I read the function specifications in gl_list.h, the use of
> imperative voice ("Return true if ...") feels wrong. "Returns true if ..." is
> the correct grammar.
>
> Why? Because imperative form is used to instruct someone. In the context
> of the documentation of a function, there are two "who"s involved:
>   - (A) the programmer who implemented the function,
>   - (B) the programmer who wants to invoke the function.
> Thus, the only valid use of imperative form in this context is an
> instruction for (B), for example: "Don't pass a negative value as argument."
>
> Things are different inside the function definition: Here, (B) is not
> supposed to look. The two "who"s here are:
>   - (A) the programmer who implemented the function,
>   - (C) the machine which executes the code.
> Here, an imperative voice from (A) to (C) is reasonable.
>
> The Python people get this wrong [1]. Probably because they put the
> specification of a function at the beginning of the function definition,
> and thus blur the distinction between documentation and function definition.
>
> [1] https://www.python.org/dev/peps/pep-0257/
>
>
> 2020-02-02  Bruno Haible  <address@hidden>
>
>         list, set, oset, map, omap: Avoid imperative voice in documentation.
>         * lib/gl_list.h: Use descriptive sentences instead of imperative voice
>         in the specification of functions.
>         * lib/gl_set.h: Likewise.
>         * lib/gl_oset.h: Likewise.
>         * lib/gl_map.h: Likewise.
>         * lib/gl_omap.h: Likewise.
>         * lib/gl_*.h: Likewise.

Hi Bruno,

I have made so many s/Returns/Return/ changes that I have a visceral
negative reaction to this change.

Perhaps it's because I have been writing deliberately imperative and
active-voice comments for so long that I find no ambiguity there. I
find those comments to be grammatically correct and easier to read
than the other forms. Also more concise, even if often only by one
letter. If I must speak of constraints on what the caller does, I'd
say something like "Freeing FOO is the responsibility of the caller."

IMHO, it is obvious from the context that the comment is not telling
"(B) the programmer who wants to invoke the function" to return.

Perhaps as in those python guidelines, I do not think it is worthwhile
to use different writing styles/voices between header and non-header
files.

Thank you for your indefatigable work on gnulib!

Jim