Paul Eggert wrote:
> I'm more familiar with the longstanding tradition of Emacs, where the
> manual says "This function returns X." and the doc strings (which is
> closer to what we're talking about here) say "Return X." In both cases
> English-language sentences are used.
>
> Of course other styles are possible.
This "Returns ..." style is not only possible. It is also what the
majority of the reference manuals out there use — from Common Lisp to Rust.
My other point is that when an imperative is used, it _ought_ to be
directed to the programmer who uses the API, not to an imagined persona
that executes code. It is confusing to have doc like this:
(defun re-enqueue (event)
"Put the event back into the event queue.
Deactivate the event listeners before, to avoid endless recursion."
Here the "Deactivate the event listeners before" imperative goes to
the programmer. If both sentences are in imperative form, no one can
understand this.
Bruno
