[Top][All Lists]

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

Re: When will emacs 27.1 be officially released?

From: Tassilo Horn
Subject: Re: When will emacs 27.1 be officially released?
Date: Thu, 02 Jul 2020 22:55:35 +0200
User-agent: Gnus/5.13 (Gnus v5.13) Emacs/28.0.50 (gnu/linux)

Paul Eggert <eggert@cs.ucla.edu> writes:

>> I just looked at the docs and it seems that in large parts the
>> function descriptions in the manual read
>>   This function takes a @var{coin} and returns a @var{beer}.
>> (indicative) whereas the docstring reads
>>   Take a COIN and return a BEER.
>> (imperative).  I know the latter is our convention for function
>> docstrings.  Is the former our convention for documenting functions
>> in the manual?
> Yes but I'd rather we switched to imperative, for consistency and
> brevity.

I'm all for consistency though the imperative style feels a bit awkward
to me.  Oftentimes, it's applied only to the first sentence of a
docstring and not completely.  For example, find-file-noselect's
docstring almost gets it right but then has the indicative sentence

  The buffer is not selected, just returned to the caller.

in the middle instead of the proper

  Do not select the buffer, just return it to the caller.


reply via email to

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