[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:29:13 +0200
User-agent: Gnus/5.13 (Gnus v5.13) Emacs/28.0.50 (gnu/linux)

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

>>> A method that works reasonably well in other projects is to update
>>> manuals and NEWS as we go, not just before a release.
>> I started requesting that some time ago, with limited success.
> Is there some way we could step that up?  E.g., perhaps start by
> reminding people who commit code changes but not changes to the
> corresponding documentation that they need to do the documenation

It would be awesome if there was an automatic way to check if some code
I have touched is already documented in the manual and might require
adaption, i.e., diff in, links to relevant parts of the manual out.  I
think it occurred to me a few times that I've added another argument to
some function, for example, and didn't even realize that this function
was documented in the manual.

What would also be nice was a way to write something like


which would be replaced by

  @defun my-function arg
  Docstring of my-function where ARG is replaced with @{arg}.
  @end defun

because at least in the Elisp manual, most function and variable
descriptions are (almost) identical to the corresponding docstrings

BTW, 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?


reply via email to

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