* bug#13923: 24.3.50; doc strings of Isearch commands
@ 2013-03-11 16:03 Drew Adams
2013-04-29 6:50 ` Juri Linkov
0 siblings, 1 reply; 5+ messages in thread
From: Drew Adams @ 2013-03-11 16:03 UTC (permalink / raw)
To: 13923
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'
^ permalink raw reply [flat|nested] 5+ messages in thread
* bug#13923: 24.3.50; doc strings of Isearch commands
2013-03-11 16:03 bug#13923: 24.3.50; doc strings of Isearch commands Drew Adams
@ 2013-04-29 6:50 ` Juri Linkov
2013-04-29 13:42 ` Drew Adams
0 siblings, 1 reply; 5+ messages in thread
From: Juri Linkov @ 2013-04-29 6:50 UTC (permalink / raw)
To: Drew Adams; +Cc: 13923
> 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.
^ permalink raw reply [flat|nested] 5+ messages in thread
* bug#13923: 24.3.50; doc strings of Isearch commands
2013-04-29 6:50 ` Juri Linkov
@ 2013-04-29 13:42 ` Drew Adams
2013-04-30 6:54 ` Juri Linkov
0 siblings, 1 reply; 5+ messages in thread
From: Drew Adams @ 2013-04-29 13:42 UTC (permalink / raw)
To: 'Juri Linkov'; +Cc: 13923
> > 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.
^ permalink raw reply [flat|nested] 5+ messages in thread
* bug#13923: 24.3.50; doc strings of Isearch commands
2013-04-29 13:42 ` Drew Adams
@ 2013-04-30 6:54 ` Juri Linkov
2013-04-30 13:22 ` Drew Adams
0 siblings, 1 reply; 5+ messages in thread
From: Juri Linkov @ 2013-04-30 6:54 UTC (permalink / raw)
To: Drew Adams; +Cc: 13923
> 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
^ permalink raw reply [flat|nested] 5+ messages in thread
* bug#13923: 24.3.50; doc strings of Isearch commands
2013-04-30 6:54 ` Juri Linkov
@ 2013-04-30 13:22 ` Drew Adams
0 siblings, 0 replies; 5+ messages in thread
From: Drew Adams @ 2013-04-30 13:22 UTC (permalink / raw)
To: 'Juri Linkov'; +Cc: 13923
> > 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.
^ permalink raw reply [flat|nested] 5+ messages in thread
end of thread, other threads:[~2013-04-30 13:22 UTC | newest]
Thread overview: 5+ messages (download: mbox.gz follow: Atom feed
-- links below jump to the message on this page --
2013-03-11 16:03 bug#13923: 24.3.50; doc strings of Isearch commands Drew Adams
2013-04-29 6:50 ` Juri Linkov
2013-04-29 13:42 ` Drew Adams
2013-04-30 6:54 ` Juri Linkov
2013-04-30 13:22 ` Drew Adams
Code repositories for project(s) associated with this external index
https://git.savannah.gnu.org/cgit/emacs.git
https://git.savannah.gnu.org/cgit/emacs/org-mode.git
This is an external index of several public inboxes,
see mirroring instructions on how to clone and mirror
all data and code used by this external index.