bug#6486: documentation of `byte-code-function-p' should mention `symbol-function' and xref manual

[MON KEY <monkey@sandpframing.com>]

Kevin Rodgers wrote:
>> How is the user supposed to know that OBJECT will only return t if
>> it is the unreadable vector returned by `symbol-function'?

> From (elisp)What Is a Function:
>   Unlike `functionp', the next three functions do _not_ treat a
> symbol as its function definition.

This doesn't address the "unreadable vector" return value though.

It says (briefly) that we may have such a thing returned but not under
which circumstances nor does it say what to do with such a thing once
we have hold of it.  e.g. that

 (require 'disass) ;; assuming it isn't loaded yet
 (vconcat (symbol-function 'disassemble-internal))

will return something readable.

>> Please add documentation of such, along with info node xref such
>> as: See info node `(elisp) Byte-Code Objects'

> Nah, that is why we have M-x elisp-index-search --

So why then do certain function docs do have info node xrefs.

If including info xrefs in docstrings extends clarity where there was
none before what is the disadvantage to adding one here for
`byte-code-function-p' as well?

Why is Juri Linkov working on extending info like capablities to
`help-mode' and vice versa?

Because having relevant documentation at hand is useful.
Especially so since,

      "Emacs is the extensible, customizable,
 -->  self-documenting real-time display editor."

Besides, last I checked Info was a separate (though incestuously
coupled) facility from Emacs. e.g. from command-line:

 $> info emacs

The point being that where info might provide additional relevant
information w/re `byte-code-function-p' it does so only tangentially.

IOW `byte-code-function-p' is to Emacs-Lisp as the `lsearch' function
is to libc. That each is documented by the Info facility does not mean
that Emacs Lisp doesnn't maintain an internal documentation consistent
with its usage.

> although it might be nice if such links were automatically generated
> by the describe-* commands.

Yes well, hooking this into describe-* commands will most-likely
require the implementor(s) to understand usage of the
`byte-code-function-p' predicate :P

This goes doubly so for those wishing to extend such a feature to
third party packages...

>> Also, note that the nature of the data-structure/readability of a
>> byte-code'd function can not be deduced by the user by simply
>> reading the manual section:
>> (info "(elisp)What Is a Function")

> The nature of several types can't be deduced by the node that
> describes the corresponding predicate, but by the node that actually
> describes the type (under the Programming Types or Editing Types
> node).

The problem in this particular circumstance is that the objects
returnd by `symbol-function' and `indirect-function' are:

 a) variadic according to whether the function is subr'd, byte-code'd,
    interpreted, indirect'd, macro'd, autoload'd

    (byte-code-function-p (symbol-function 'concat))
    ;=> nil

    (symbol-function 'concat)
    ;=> #<subr concat>

    (subrp (symbol-function 'concat))
    ;=>t

    (symbol-function 'with-current-buffer)
    ;=> (macro . #[<BIG-UNREADABE-VECTOR-HERE> ... ])

    (symbol-function 'lisp-mode)
    ;=> #[ <BIG-UNREADABE-VECTOR-HERE> ... ]

    (symbol-function 'common-lisp-mode)
    ;=> lisp-mode

    (indirect-function 'common-lisp-mode)
    ;=> #[ <BIG-UNREADABE-VECTOR-HERE> ... ]

    (eq (indirect-function 'common-lisp-mode)
        (symbol-function 'lisp-mode))
    ;=> t

    (symbol-function 'dunnet)
    ;=> (autoload "dunnet" 940287 t nil)

    (byte-code-function-p (symbol-function 'dunnet))
    ;=> nil

    (require 'dunnet)
    ;=> brought autoload'd symbol `dunnet' into environment.

    (symbol-function 'dunnet)
    ;=> #[ <BIG-UNREADABE-VECTOR-HERE> ... ]

    (byte-code-function-p (symbol-function 'dunnet))
    ;=> t

    (defun my-bubba (x)
     "bubba returns t when X is eq X."
    (eq x x))

    (symbol-function 'my-bubba)
    ;=> (lambda (x) "bubba returns t when X is eq X." (eq x x))

    (defalias 'bubba-in-disguise 'my-bubba)

    (symbol-function 'bubba-in-disguise)
    ;=> my-bubba

    (indirect-function 'bubba-in-disguise)
    ;=> (lambda (x) "bubba returns t when X is eq X." (eq x x))

    (byte-compile 'my-bubba)
    ;=> #[(x) "\x8\211=\207" [x] 2 "bubba returns t when X is eq X."]

    (symbol-function 'my-bubba)
    ;=> #[(x) "\x8\211=\207" [x] 2 "bubba returns t when X is eq X."]

    (symbol-function 'bubba-in-disguise)
    ;=> my-bubba

    (indirect-function 'bubba-in-disguise)
    ;=> #[(x) "\x8\211=\207" [x] 2 "bubba returns t when X is eq X."]

 b) apropos a two of the "types" of return values above aren't readable

 c) apropos b one of the "types" can't even be coerced into readability.

    e.g. this is coercable:
    (vconcat (cdr (symbol-function 'with-current-buffer)))

    :NOTE FOLLOWING FORM MAY HANG
               EVAL IN A DISPOSABLE Emacs!

    this is not:
    (read (symbol-function 'concat))

 c) apropos b and c, and because we don't have features like
    `print-unreadable-object' or `readably-printable' to help us w/
    frobbing "type" it is important that the user be afforded some
    additional clarity within the docs independently of the manual
    w/re how to accomplish such things.

> (elisp)What Is a Function does say:
> "byte-code function"
>      A "byte-code function" is a function that has been compiled by the
>      byte compiler.  *Note Byte-Code Type::.

Unless it is a subr or an autoload or a macro...

See above.

> And (elisp)Byte-Code Type (referenced above) says:
>
>   The printed representation and read syntax for a byte-code function
> object is like that for a vector, with an additional `#' before the
> opening `['.

So, currently an un-informed user now has to xref 3x info nodes:

 (info "(elisp)Byte-Code Type")
 (info "(elisp)Byte-Code Objects")
 (info "(elisp)What Is a Function")

To reach the conclusion that the OBJECT arg to byte-code-function-p is
(with qualifications) per the return value of `symbol-function',
`indirect-function'.

This is why I feel justified in asserting that the docstring of
`byte-code-function-p',

 "does not adequately indicate that the OBJECT arg is as per the return
  value of `symbol-function'."

And requested that,

 "documentation of such, along with info node xref such as:

  See info node `(elisp) Byte-Code Objects'"

be provided.

Neither of which strike me as all that unreasonable.

> Kevin Rodgers

--
/s_P\