bug#13923: 24.3.50; doc strings of Isearch commands

bug#13923: 24.3.50; doc strings of Isearch commands

[Drew Adams]

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@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'
 

bug#13923: 24.3.50; doc strings of Isearch commands

[Juri Linkov]

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

bug#13923: 24.3.50; doc strings of Isearch commands

[Drew Adams]

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

bug#13923: 24.3.50; doc strings of Isearch commands

[Juri Linkov]

> 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

bug#13923: 24.3.50; doc strings of Isearch commands

[Drew Adams]

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