[Top][All Lists]

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

Re: doc string of `local-variable-if-set-p'

From: Luc Teirlinck
Subject: Re: doc string of `local-variable-if-set-p'
Date: Thu, 14 Oct 2004 23:12:30 -0500 (CDT)

Daniel Brockman wrote:

   Or am I missing some long-established Emacs documentation convention?

Actually there is a convention in the Elisp manual to call the
argument BUFFER if it has to be a buffer and BUFFER-OR-NAME if it can
be a buffer or a buffer name.  That convention is consistently
followed in the Elisp manual, but not in docstrings.  So one can not
just rely on it in docstrings.

   Still, I think that's a detail that belongs somewhere after the
   space-constrained first line.

The space constraint is 67 characters or less, so it will not look bad
in the apropos output. So 66 is perfectly acceptable.

   Just doubling the word ``buffer'' isn't going to make it clear that
   a buffer *name* won't do, so you might as well spell it out clearly
   in the long description.

OK, so what about:

DEFUN ("local-variable-if-set-p", Flocal_variable_if_set_p, 
       1, 2, 0,
       doc: /* Non-nil if VARIABLE will be local in BUFFER when set there.
More precisely, this means that setting the variable \(with `set' or`setq'),
while it does not have a `let'-style binding that was made in BUFFER,
will produce a buffer local binding.  See Info node
`(elisp)Creating Buffer-Local'.
BUFFER must be a buffer \(not a buffer name) and defaults to
the current buffer.  */)

reply via email to

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