[Top][All Lists]

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

Re: Trunk still not open

From: Stephen J. Turnbull
Subject: Re: Trunk still not open
Date: Mon, 17 Mar 2014 13:33:04 +0900

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


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

reply via email to

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