GNU bug report logs - #6497
documentation `indirect-function', `symbol-function' do not enumerate return value type

Previous Next

Full log

View this message in rfc822 format

From: help-debbugs <at> gnu.org (GNU bug Tracking System)
To: Glenn Morris <rgm <at> gnu.org>
Cc: tracker <at> debbugs.gnu.org
Subject: bug#6497: closed (documentation `indirect-function',
 `symbol-function' do not enumerate  return value type)
Date: Sat, 09 Jul 2011 18:26:02 +0000

[Message part 1 (text/plain, inline)]

Your message dated Sat, 09 Jul 2011 14:25:13 -0400
with message-id <a3tyav5n1y.fsf_-_ <at> fencepost.gnu.org>
and subject line Re: bug#6497: documentation `indirect-function', `symbol-function' do not enumerate return value type
has caused the GNU bug report #6497,
regarding documentation `indirect-function', `symbol-function' do not enumerate  return value type
to be marked as done.

(If you believe you have received this mail in error, please contact
help-debbugs <at> gnu.org.)


-- 
6497: http://debbugs.gnu.org/cgi/bugreport.cgi?bug=6497
GNU Bug Tracking System
Contact help-debbugs <at> gnu.org with problems

[Message part 2 (message/rfc822, inline)]

From: MON KEY <monkey <at> sandpframing.com>
To: bug-gnu-emacs <at> gnu.org
Subject: documentation `indirect-function', `symbol-function' do not enumerate 
	return value type
Date: Tue, 22 Jun 2010 19:42:57 -0400

documentation of function `indirect-function' and `symbol-function' do
not adequately enumerate all of the types of return values (nor does
it even make mention of them) and docstring of `indirect-function' too
closeley mirrors that of `indirect-variable'.

Additionally, the value of its argument OBJECT does not reflect that
of the `symbol-function' arg SYMBOL it should because its return value
more closely resembles that of `symbol-function' than
`indirect-variable'.


,---- (documentation 'indirect-variable)
|
| Return the variable at the end of OBJECT's variable chain.
| If OBJECT is a symbol, follow all variable indirections and return the
| final variable.  If OBJECT is not a symbol, just return it.  Signal a
| cyclic-variable-indirection error if there is a loop in the variable
| chain of symbols.
|
| (fn OBJECT)
|
`----

,---- (documentation 'indirect-function)
|
| Return the function at the end of OBJECT's function chain.
| If OBJECT is not a symbol, just return it.  Otherwise, follow all
| function indirections to find the final function binding and return
| it.  If the final symbol in the chain is unbound, signal a
| void-function error.  Optional arg NOERROR non-nil means to return nil
| instead of signalling.  Signal a cyclic-function-indirection error if
| there is a loop in the function chain of symbols.
|
| (fn OBJECT &optional NOERROR)
|
`----

,---- (documentation 'symbol-function)
|
| Return SYMBOL's function definition.  Error if that is void.
|
| (fn SYMBOL)
|
`----

Given the similarity of docstrings for `indirect-variable' and
`indirect-function' it is possible for a user to assume the quoting
rules of `indirect-variable' apply as well to `indirect-function'.

In the following example `indirect-variable' returns regardless of
whether the arg OBJECT is quoted:

 (indirect-variable font-lock-comment-face)
 (indirect-variable 'font-lock-comment-face)

Whereas, in the following evaluation of `indirect-function'  the first
 use of an arg as unquoted symbol signals an error.

 (indirect-function lisp-mode-variables)
 (indirect-function 'lisp-mode-variables)

This problem isn't an issue were it not for the close resemblance of
the `indirect-function' `indirect-variable' docstrings.

More troublesome though is that neither `indirect-function' nor
`symbol-function' document their return values in any meaningful way:

Following is an attempt at fleshing out those return values not
specified by the existing docstrings (substitute OBJECT for SYMBOL
accordingly):

,----
|
| If OBJECT satisfies the predicate `subrp' return an unreadable
| object of the form:
|
|  #<subr SOME-SUBR-NAME>
|
| If OBJECT is an "autuload object" type its return value is a list of
| values suitable for use as arguments to the `autoload' function and
| of the form:
|
|  (autoload "<FILENAME>" <DOCSTRING-POSN> <INTERACTIVE> <TYPE>)
|
| Note, the <TYPE> element for OBJECT's return value as "autoload
| object" is nil for a function and `macro' or `t' for a macro.
|
| If value of OBJECT is a "byte-code function" type, e.g. it would
| satisfy the predicate `byte-code-function-p', and OBJECT is not a
| "Lisp macro" its value is returned as an unreadable vector of the
| form:
|
|  #[ ... ]
|
| if OBJECT is a "Lisp macro" in it value is returned as a cons of the
| form:
|
|  (macro . #[ ... ])
|
`----

--
/s_P\

[Message part 3 (message/rfc822, inline)]

From: Glenn Morris <rgm <at> gnu.org>
To: 6497-done <at> debbugs.gnu.org
Subject: Re: bug#6497: documentation `indirect-function',
	`symbol-function' do not enumerate return value type
Date: Sat, 09 Jul 2011 14:25:13 -0400

I don't see a need to keep open this particular report.

Previous Next

GNU bug tracking system
Copyright (C) 1999 Darren O. Benham, 1997,2003 nCipher Corporation Ltd, 1994-97 Ian Jackson.