bug#23061: 25.0.92; Docs of ARGLIST in byte-code function objects is outdated

[Eli Zaretskii]

The node "Byte-Code Objects" says:

     Internally, a byte-code function object is much like a vector; its
  elements can be accessed using ‘aref’.  Its printed representation is
  like that for a vector, with an additional ‘#’ before the opening ‘[’.
  It must have at least four elements; there is no maximum number, but
  only the first six elements have any normal use.  They are:

  ARGLIST
       The list of argument symbols.

  BYTE-CODE
       The string containing the byte-code instructions.
  ...

and gives this example:

     Here’s an example of a byte-code function object, in printed
  representation.  It is the definition of the command ‘backward-sexp’.

       #[(&optional arg)
         "^H\204^F^@\301^P\302^H[!\207"
         [arg 1 forward-sexp]
         2
         254435
         "^p"]

However, if you actually try this example, you get a different result:

 (symbol-function 'backward-sexp)
  => #[256 "\211\204^G^@\300\262^A\301^A[!\207" [1 forward-sexp] 3 1793299 "^p"]

IOW, instead of the argument list you have a number 256.  Neither the
fact that it can be (and usually is) a number nor the ways to
interpret that number are documented anywhere I could see.

It looks like the information about this can be found in
byte-compile-make-args-desc and help-function-arglist.

The change which introduced this feature was done 5 years ago, so it's
high time we had it documented.


In GNU Emacs 25.0.92.36 (i686-pc-mingw32)
 of 2016-03-19 built on HOME-C4E4A596F7
Repository revision: 26f9c5075ff273013418a66b70fae477301d41d5
Windowing system distributor 'Microsoft Corp.', version 5.1.2600
Configured using:
 'configure --prefix=/d/usr --enable-checking=yes,glyphs --with-wide-int
 --with-modules 'CFLAGS=-O0 -gdwarf-4 -g3''

Configured features:
XPM JPEG TIFF GIF PNG RSVG SOUND NOTIFY ACL GNUTLS LIBXML2 ZLIB
TOOLKIT_SCROLL_BARS MODULES

Important settings:
  value of $LANG: ENU
  locale-coding-system: cp1255

Major mode: Lisp Interaction

Minor modes in effect:
  diff-auto-refine-mode: t
  tooltip-mode: t
  global-eldoc-mode: t
  electric-indent-mode: t
  mouse-wheel-mode: t
  tool-bar-mode: t
  menu-bar-mode: t
  file-name-shadow-mode: t
  global-font-lock-mode: t
  font-lock-mode: t
  blink-cursor-mode: t
  auto-composition-mode: t
  auto-encryption-mode: t
  auto-compression-mode: t
  line-number-mode: t
  transient-mark-mode: t

Recent messages:
For information about GNU Emacs and the GNU system, type C-h C-a.
Type C-x 1 to delete the help window.

Making completion list...

Load-path shadows:
None found.

Features:
(shadow sort mail-extr emacsbug message dired format-spec rfc822 mml
mml-sec password-cache epg epg-config gnus-util mm-decode mm-bodies
mm-encode mail-parse rfc2231 mailabbrev gmm-utils mailheader sendmail
rfc2047 rfc2045 ietf-drums mm-util mail-prsvr mail-utils dabbrev vc
vc-dispatcher vc-git diff-mode easy-mmode find-func cl-extra thingatpt
help-fns help-mode easymenu cl-loaddefs pcase cl-lib time-date mule-util
tooltip eldoc electric uniquify ediff-hook vc-hooks lisp-float-type
mwheel dos-w32 ls-lisp disp-table w32-win w32-vars term/common-win
tool-bar dnd fontset image regexp-opt fringe tabulated-list newcomment
elisp-mode lisp-mode prog-mode register page menu-bar rfn-eshadow timer
select scroll-bar mouse jit-lock font-lock syntax facemenu font-core
frame cl-generic cham georgian utf-8-lang misc-lang vietnamese tibetan
thai tai-viet lao korean japanese eucjp-ms cp51932 hebrew greek romanian
slovak czech european ethiopic indian cyrillic chinese charscript
case-table epa-hook jka-cmpr-hook help simple abbrev minibuffer
cl-preloaded nadvice loaddefs button faces cus-face macroexp files
text-properties overlay sha1 md5 base64 format env code-pages mule
custom widget hashtable-print-readable backquote w32notify w32 multi-tty
make-network-process emacs)

Memory information:
((conses 16 101168 7624)
 (symbols 56 21418 0)
 (miscs 48 46 181)
 (strings 16 20509 5825)
 (string-bytes 1 519374)
 (vectors 16 13539)
 (vector-slots 8 440543 4313)
 (floats 8 173 473)
 (intervals 40 633 215)
 (buffers 856 14))