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: MON KEY <monkey <at> sandpframing.com>
Subject: bug#6497: closed (Re: bug#6497: 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 bug report

#6497: documentation `indirect-function', `symbol-function' do not enumerate  return value type

which was filed against the emacs package, has been closed.

The explanation is attached below, along with your original report.
If you require more details, please reply to 6497 <at> debbugs.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: 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.

[Message part 3 (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\

Previous Next

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