Re: When will emacs 27.1 be officially released?

[Tassilo Horn <tsdh@gnu.org>]

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
> ASAP.

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

  @IncludeEmacsDefunDocs{my-function}{lisp/my.el}

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
anyway.

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?

Bye,
Tassilo