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

[Kevin Rodgers]

MON KEY wrote:
> The documentation of function `byte-code-function-p' should mention
> usage requires `symbol-function', and/or should refer to a relevant
> portion of the manual.
>
> ,---- (documentation 'byte-code-function-p)
> |
> | Return t if OBJECT is a byte-compiled function object.
> |
> | (fn OBJECT)
> |
> `----
>
> The above docs do not adequately indicate that the OBJECT arg is as
> per the return value of `symbol-function'. e.g.:
>
>  (byte-code-function-p 'disassemble)
>  ;=> nil
>
>  (byte-code-function-p (symbol-function 'disassemble))
>  ;=> t
>
> 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.

 -- Function: subrp object
 ...
 -- Function: byte-code-function-p object

     This function returns `t' if OBJECT is a byte-code function.  For
     example:

          (byte-code-function-p (symbol-function 'next-line))
               => t

 -- Function: subr-arity subr
...

> 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 -- although it might
be nice if such links were automatically generated by the describe-*
commands.

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

(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::.

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

--
Kevin Rodgers
Denver, Colorado, USA