On Fri, Jan 3, 2025 at 8:04 PM Bruno Haible via Gnulib discussion list <bug-gnulib@gnu.org> wrote: > > 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.
Hi Bruno, I'm surprised that you would use "more sources use Y" as a rationale for using Y. I too prefer the usually-more-concise "Return X". > 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. To espouse one form or the other does not mean every sentence must fit the mold.
