Re: Trunk still not open

[Stephen J. Turnbull]

Dmitry Gutov writes:
 > On 14.03.2014 17:39, Stephen J. Turnbull wrote:
 > > If you have XEmacs docstrings, in many cases, yes, but Emacs generally
 > > doesn't put enough semantic information in docstrings to define the
 > > corner cases where tests actually make a big difference.  You need the
 > > manual level of detail.
 > 
 > If the docstring doesn't describe the corner cases, they're usually not 
 > important for the user to know

True.

 > (what will they be doing in the manual, then?),

Providing documentation for the unusual user or unusual use case --
including the folks who write tests.

 > or it's a bug in the docstring.

In XEmacs you'd quite possibly be right, but AIUI, no, not in Emacs.
In Emacs docstrings are to explain the basic function plus the syntax
of different arguments.  Detailed explanation of semantics is left to
the manual.  To take an absolutely obvious case (where even XEmacs
would refuse a patch to provide completely detailed semantics of a
function), consider "looking-at".  The REGEXP argument is described
(surprisingly enough) as a regular expression.  The Emacs dialect of
regular expression, however, is not explained in detail (and this is
true in *all* regexp-accepting functions).

But in the manual it should be explained, and tests should make sure
that all syntax in the manual is accepted and functions properly.

 > This is probably different for some large/core features, but on
 > most of the features I've worked with, the manual rarely provides a
 > lot of value.

That's a shame.