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

[Bruno Haible]

Hi Jim,

> Perhaps it's because I have been writing deliberately imperative and
> active-voice comments for so long that I find no ambiguity there.

Yes, 13 years ago, apparently I used this style as well. Nowadays I'm
used to the descriptive style, because it is more established. [1]

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

Even in GNU, and specifically in Emacs Lisp, it's inconsistent: While
the Emacs "Tips for Documentation Strings" [2] asks for imperative style,
large parts of the Emacs Reference Documentation [3] have switched to
"This function <descriptive style>". For example
"This function returns t ..." [4].

> 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.

Yes, function descriptions in non-header files (for 'static' functions)
should be treated like function descriptions in header files, IMO.

The real difference is: Am I talking to a user of the function? Or am
I explaining the implementation details of the function?

Bruno

[1] http://lua-users.org/lists/lua-l/2012-03/msg00785.html
[2] 
https://www.gnu.org/software/emacs/manual/html_node/elisp/Documentation-Tips.html
[3] https://www.gnu.org/software/emacs/manual/html_node/elisp/index.html
[4] https://www.gnu.org/software/emacs/manual/html_node/elisp/Symbols.html