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

Previous Next

Full log

Message #11 received at 6497 <at> debbugs.gnu.org (full text, mbox):

From: MON KEY <monkey <at> sandpframing.com>
To: Geoff Gole <geoffgole <at> gmail.com>
Cc: 6497 <at> debbugs.gnu.org
Subject: Re: 6497
Date: Thu, 1 Jul 2010 20:13:18 -0400

On Thu, Jul 1, 2010 at 5:20 AM, Geoff Gole <geoffgole <at> gmail.com> wrote:

> 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'.

>> There are no "quoting rules" for indirect-variable or

When given an unquoted symbol as its argument `indirect-variable' will
return the value of a non-null symbol. That it does so represents a
subtle alteration of the generally expected semantics e.g. wheras
`indirect-function' does signal an error.

>> indirect-function. They are regular functions and have the same
>> argument evaluation semantics as every other regular function.

Neither are regular lisp functions they are both primitives defined in
src/data.c

     (symbol-function 'indirect-function)
     (symbol-function 'indirect-variable)

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

>> They mention that they return a "function definition",
Except, that they don't always. which the docstring is in error.

>> which is appropriately abstract

Appropriately abstract for whom?

>> given that these functions don't depend in any way on the details
>> of function representation.

Sure they rely on the details of the function representation:

(symbol-function 'not-a-real-function)
 => (void-function not-a-real-function)

(symbol-functiol not-a-real-function)
=> (void-function symbol-functiol)

(symbol-function indirect-function)
=> (void-variable indirect-function)   ;; <-- void-variable

(indirect-function 'not-a-real-function)
=> (void-function not-a-real-function)

(indirect-function not-a-real-function)
=> (void-variable not-a-real-function) ;; <-- void-variable

(indirect-function symbol-function)
=> (void-variable symbol-function)     ;; <-- void-variable

How do these primitives reach determination that the function cell of
`not-a-real-function' is void if they don't access som portion of the
representation denoting that symbol is function/variable?

>> Function values are already documented in detail elsewhere, and

In detail and across a wide range. e.g.:

- See bug#6496 re autoload objects not appearing in "What is a
  function" node in manual.

- See bug#6486 re `byte-code-function-p' requiring the user to cross
  reference 3x info nodes in order to conclude that its return value
  is as per `symbol-function'.


>> duplicating that documentation would not be helpful.

Would not be helful for whom?

`symbol-function' and `indirect-function' are the cannonical
interfaces by which one can access the function cell of a symbol.

The docstring of `symbol-function' is a terse one sentence and doesn't
provide any indication that the _readability_ of its return value
varies significantly acording to the type of function given as the
arugment.

Really, symbol-function and his buddy `indirect-function' return:

 - a lambda form
 - a vector
 - a list
 - a cons
 - and two types of unreadable objects

I would suggest this is is abnormal compared w/ the vast majority of
Emacs lisp functions' return values.

--
/s_P\

Previous Next

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