GNU bug report logs -
#13923
24.3.50; doc strings of Isearch commands
Previous Next
Reported by: "Drew Adams" <drew.adams <at> oracle.com>
Date: Mon, 11 Mar 2013 16:06:01 UTC
Severity: minor
Found in version 24.3.50
Done: Juri Linkov <juri <at> jurta.org>
Bug is archived. No further changes may be made.
Full log
Message #11 received at 13923 <at> debbugs.gnu.org (full text, mbox):
> > 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.
This bug report was last modified 12 years and 82 days ago.
Previous Next
GNU bug tracking system
Copyright (C) 1999 Darren O. Benham,
1997,2003 nCipher Corporation Ltd,
1994-97 Ian Jackson.