Re: When will emacs 27.1 be officially released?

[Eli Zaretskii]

> From: Tassilo Horn <tsdh@gnu.org>
> Cc: Eli Zaretskii <eliz@gnu.org>,  liwei.ma@gmail.com,  emacs-devel@gnu.org,
>   kevin.legouguec@gmail.com
> Date: Thu, 02 Jul 2020 22:29:13 +0200
> 
> 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.

I think "most" and "almost identical" is inaccurate here.  IME, most
of the descriptions in the manual are quite different from the doc
strings.

Doc strings have some limitations you need to observe: the first line
has to be a complete sentence and should mention the arguments; the
text should be short enough; there are some subtle rules for
referencing symbols that shouldn't produce hyperlinks; etc.  Living
with these limitations in the manual as well will produce suboptimal
text, IMO.

The (quite extreme, IMO) result of doing what you propose is the GNU
Guile manual: the Guile build procedure "snarfs" the doc strings from
the source code and produces 90% of the manual's text from them.  The
result is not a very good manual, at least IMO.  Just compare it with
the ELisp manual, and make your own conclusions about quality.

And then there's the user manual, where the doc strings are definitely
not the way to go, I hope you will agree.

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

Yes.  Just one of those minor stylistic differences that make the
manual a good reading, whereas the doc strings are terse and
functional.