[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index]
bug#13923: 24.3.50; doc strings of Isearch commands
From: |
Drew Adams |
Subject: |
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.