From: MON KEY <monkey@sandpframing.com>
To: 6497@debbugs.gnu.org
Subject: bug#6497: documentation `indirect-function', `symbol-function' do not enumerate return value type
Date: Tue, 22 Jun 2010 19:42:57 -0400 [thread overview]
Message-ID: <AANLkTimv0lI7bJQsLfed5yVgFM-uoOsVSUPMKjoAZVTI@mail.gmail.com> (raw)
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\
next reply other threads:[~2010-06-22 23:42 UTC|newest]
Thread overview: 11+ messages / expand[flat|nested] mbox.gz Atom feed top
2010-06-22 23:42 MON KEY [this message]
2010-07-01 9:20 ` bug#6497: 6497 Geoff Gole
2010-07-02 0:13 ` MON KEY
2010-07-02 1:39 ` Geoff Gole
2010-07-03 4:27 ` MON KEY
2010-07-03 6:31 ` Geoff Gole
2010-07-03 19:35 ` MON KEY
2010-07-03 7:00 ` Andreas Schwab
2010-07-03 19:33 ` MON KEY
2010-07-03 19:47 ` Andreas Schwab
2011-07-09 18:25 ` bug#6497: documentation `indirect-function', `symbol-function' do not enumerate return value type Glenn Morris
Reply instructions:
You may reply publicly to this message via plain-text email
using any one of the following methods:
* Save the following mbox file, import it into your mail client,
and reply-to-all from there: mbox
Avoid top-posting and favor interleaved quoting:
https://en.wikipedia.org/wiki/Posting_style#Interleaved_style
* Reply using the --to, --cc, and --in-reply-to
switches of git-send-email(1):
git send-email \
--in-reply-to=AANLkTimv0lI7bJQsLfed5yVgFM-uoOsVSUPMKjoAZVTI@mail.gmail.com \
--to=monkey@sandpframing.com \
--cc=6497@debbugs.gnu.org \
/path/to/YOUR_REPLY
https://kernel.org/pub/software/scm/git/docs/git-send-email.html
* If your mail client supports setting the In-Reply-To header
via mailto: links, try the mailto: link
Be sure your reply has a Subject: header at the top and a blank line
before the message body.
Code repositories for project(s) associated with this external index
https://git.savannah.gnu.org/cgit/emacs.git
https://git.savannah.gnu.org/cgit/emacs/org-mode.git
This is an external index of several public inboxes,
see mirroring instructions on how to clone and mirror
all data and code used by this external index.