I've several times hesitated when writing a docstring: should it document
the function or the command.
The command is the same entity as the function. You're talking about
two different ways of calling it, interactively and noninteractively.
The doc string for a command should describe both methods of calling.
I think it is usually best to explain interactive use first, then
explain the rules for a noninteractive call.
The more typical problem is whether to refer to ARG, BEG, END or to
\\[universal-argument], and the region.
One approach is to start out saying "the region" and/or "prefix
argument", but also give the argument names through which the function
gets them. That is one way to document primarily interactive calling
while also explaining noninteractive calling.
_______________________________________________
Emacs-devel mailing list
Emacs-devel@gnu.org
http://lists.gnu.org/mailman/listinfo/emacs-devel
