[Top][All Lists]

[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index]

Re: "What's This?" in Describe submenu

From: Richard M. Stallman
Subject: Re: "What's This?" in Describe submenu
Date: Wed, 24 Aug 2005 06:33:04 -0400

    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.

reply via email to

[Prev in Thread] Current Thread [Next in Thread]