GNU bug report logs - #13923
24.3.50; doc strings of Isearch commands

Previous Next

To add a comment to this bug, you must first unarchive it, by sending
a message to control AT debbugs.gnu.org, with unarchive 13923 in the body.
You can then email your comments to 13923 AT debbugs.gnu.org in the normal way.

Toggle the display of automated, internal messages from the tracker.

Message #5 received at submit <at> debbugs.gnu.org (full text, mbox):

From: "Drew Adams" <drew.adams <at> oracle.com>
To: <bug-gnu-emacs <at> gnu.org>
Subject: 24.3.50; doc strings of Isearch commands
Date: Mon, 11 Mar 2013 09:03:44 -0700

The doc strings of `isearch-forward' etc. should describe each of the
arguments.  That includes arg NO-RECURSIVE-EDIT.  This applies to all
Isearch commands.
 
The doc string of `isearch-mode', especially, needs to describe each of
its arguments.  It currently describes none of them.
 
In GNU Emacs 24.3.50.1 (i386-mingw-nt5.1.2600)
 of 2013-03-04 on ODIEONE
Bzr revision: 111935 yamaoka <at> jpl.org-20130304102733-4qy111z41qwoh2as
Windowing system distributor `Microsoft Corp.', version 5.1.2600
Configured using:
 `configure --with-gcc (4.7) --no-opt --enable-checking --cflags
 -IC:/Devel/emacs/build/include --ldflags -LC:/Devel/emacs/build/lib'
 

Message #8 received at 13923 <at> debbugs.gnu.org (full text, mbox):

From: Juri Linkov <juri <at> jurta.org>
To: "Drew Adams" <drew.adams <at> oracle.com>
Cc: 13923 <at> debbugs.gnu.org
Subject: Re: bug#13923: 24.3.50; doc strings of Isearch commands
Date: Mon, 29 Apr 2013 09:50:28 +0300

> The doc strings of `isearch-forward' etc. should describe each of the
> arguments.  That includes arg NO-RECURSIVE-EDIT.  This applies to all
> Isearch commands.

The docstring of `isearch-forward' describes the whole Isearch facility
for interactive use with all its available commands and keys.

There is only one place to describe `isearch-forward' as a non-interactive
function at the end of the docstring that already contains this text:

    If this function is called non-interactively, it does not return to
    the calling function until the search is done.

that describes the effect of NO-RECURSIVE-EDIT.

> The doc string of `isearch-mode', especially, needs to describe each of
> its arguments.  It currently describes none of them.

This is described already in the Commentary section of isearch.el:

  ;; For programmed use of isearch-mode, e.g. calling (isearch-forward),
  ;; isearch-mode behaves modally and does not return until the search
  ;; is completed.  It uses a recursive-edit to behave this way.

and in the comments of `isearch-mode':

  ;; isearch-mode can be made modal (in the sense of not returning to
  ;; the calling function until searching is completed) by entering
  ;; a recursive-edit and exiting it when done isearching.

Message #11 received at 13923 <at> debbugs.gnu.org (full text, mbox):

From: "Drew Adams" <drew.adams <at> oracle.com>
To: "'Juri Linkov'" <juri <at> jurta.org>
Cc: 13923 <at> debbugs.gnu.org
Subject: RE: bug#13923: 24.3.50; doc strings of Isearch commands
Date: Mon, 29 Apr 2013 06:42:04 -0700

> > The doc strings of `isearch-forward' etc. should describe 
> > each of the arguments.  That includes arg NO-RECURSIVE-EDIT.
> > This applies to all Isearch commands.
> 
> The docstring of `isearch-forward' describes the whole 
> Isearch facility for interactive use with all its available
> commands and keys.

On its own, irrelevant.

If you expect someone looking at the doc string for function `foo' to go to the
doc string of function `bar' to get part of `foo's description, then provide a
link from foo's doc to bar's, and make clear that the parameters correspond etc.

>  If this function is called non-interactively, it does not 
>  return to the calling function until the search is done.
> 
> that describes the effect of NO-RECURSIVE-EDIT.

Does it say that that is a description of NO-RECURSIVE-EDIT?  No.

If that is what the intention is, please make the connection, explicitly, so
user's do not have to guess that that is what you mean.

A user should be able to scan or search the doc string for a parameter name, to
find its description (especially when the doc string is long, as in this case).

> > The doc string of `isearch-mode', especially, needs to 
> > describe each of its arguments.  It currently describes
> > none of them.
> 
> This is described already in the Commentary section of isearch.el:

Irrelevant.  Which part of "doc string" is not clear?  By "self-documenting
editor", Emacs does not mean only that you can find some comments that might
help in the source code.  Emacs promises more than that.

Message #14 received at 13923 <at> debbugs.gnu.org (full text, mbox):

From: Juri Linkov <juri <at> jurta.org>
To: "Drew Adams" <drew.adams <at> oracle.com>
Cc: 13923 <at> debbugs.gnu.org
Subject: Re: bug#13923: 24.3.50; doc strings of Isearch commands
Date: Tue, 30 Apr 2013 09:54:17 +0300

> Does it say that that is a description of NO-RECURSIVE-EDIT?  No.

Thanks for bringing attention to endless omissions in docstrings.

> If that is what the intention is, please make the connection, explicitly, so
> user's do not have to guess that that is what you mean.

Does this patch do what you intended to achieve?

=== modified file 'lisp/isearch.el'
--- lisp/isearch.el	2013-04-27 22:03:42 +0000
+++ lisp/isearch.el	2013-04-30 06:54:05 +0000
@@ -735,8 +735,9 @@ (defun isearch-forward (&optional regexp
  and are then executed normally (depending on `search-exit-option').
 Likewise for function keys and mouse button events.
 
-If this function is called non-interactively, it does not return to
-the calling function until the search is done."
+If this function is called non-interactively with a nil NO-RECURSIVE-EDIT,
+it does not return to the calling function until the search is done.
+See the function `isearch-mode' for more information."
 
   (interactive "P\np")
   (isearch-mode t (not (null regexp-p)) nil (not no-recursive-edit)))
@@ -799,7 +800,23 @@ (defun isearch-backward-regexp (&optiona
 
 (defun isearch-mode (forward &optional regexp op-fun recursive-edit word)
   "Start Isearch minor mode.
-It is called by the function `isearch-forward' and other related functions."
+It is called by the function `isearch-forward' and other related functions.
+
+The non-nil arg FORWARD means searching in the forward direction.
+
+The non-nil arg REGEXP does an incremental regular expression search.
+
+The arg OP-FUN is a function to be called after each input character
+is processed.  (It is not called after characters that exit the search.)
+
+When the arg RECURSIVE-EDIT is non-nil, this function behaves modally and
+does not return to the calling function until the search is completed.
+To behave this way it enters a recursive-edit and exits it when done
+isearching.
+
+The arg WORD, if t, does incremental search for a sequence of words,
+ignoring punctuation.  If the value is a function, it is called to
+convert the search string to a regexp used by regexp search functions."
 
   ;; Initialize global vars.
   (setq isearch-forward forward

Message #17 received at 13923 <at> debbugs.gnu.org (full text, mbox):

From: "Drew Adams" <drew.adams <at> oracle.com>
To: "'Juri Linkov'" <juri <at> jurta.org>
Cc: 13923 <at> debbugs.gnu.org
Subject: RE: bug#13923: 24.3.50; doc strings of Isearch commands
Date: Tue, 30 Apr 2013 06:22:58 -0700

> > Does it say that that is a description of NO-RECURSIVE-EDIT?  No.
> 
> Thanks for bringing attention to endless omissions in docstrings.
> 
> > If that is what the intention is, please make the connection,
> > explicitly, so user's do not have to guess that that
> > is what you mean.
> 
> Does this patch do what you intended to achieve?

Yes, it is an improvement.  Thanks.

Previous Next

GNU bug tracking system
Copyright (C) 1999 Darren O. Benham, 1997,2003 nCipher Corporation Ltd, 1994-97 Ian Jackson.