[Top][All Lists]

[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index]

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

From: Bruno Haible
Subject: Re: list, set, oset, map, omap: avoid imperative voice in documentation
Date: Sun, 02 Feb 2020 18:13:21 +0100
User-agent: KMail/5.1.3 (Linux/4.4.0-171-generic; KDE/5.18.0; x86_64; ; )

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?


[1] http://lua-users.org/lists/lua-l/2012-03/msg00785.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

reply via email to

[Prev in Thread] Current Thread [Next in Thread]