2 files changed, 22 insertions, 2 deletions

diff --git a/src/buffer.h b/src/buffer.h
index 14d3aa6d5ee..930424b0b49 100644
--- a/src/buffer.h
+++ b/src/buffer.h
@@ -906,8 +906,26 @@ extern int last_per_buffer_idx;
        (B)->local_flags[IDX] = (VAL);                   \
      } while (0)
 
-/* Return the index of the per-buffer variable at offset OFFSET in the
-   buffer structure.  */
+/* Return the index value of the per-buffer variable at offset OFFSET
+   in the buffer structure.
+
+   If the slot OFFSET has a corresponding default value in
+   buffer_defaults, the index value is positive and has only one
+   nonzero bit.  When a buffer has its own local value for a slot, the
+   bit for that slot (found in the same slot in this structure) is
+   turned on in the buffer's local_flags array.
+
+   If the index value is -1, even though there may be a
+   DEFVAR_PER_BUFFER for the slot, there is no default value for it;
+   and the corresponding slot in buffer_defaults is not used.
+
+   If the index value is -2, then there is no DEFVAR_PER_BUFFER for
+   the slot, but there is a default value which is copied into each
+   new buffer.
+
+   If a slot in this structure corresponding to a DEFVAR_PER_BUFFER is
+   zero, that is a bug */
+
 
 #define PER_BUFFER_IDX(OFFSET) \
       XINT (*(Lisp_Object *)((OFFSET) + (char *) &buffer_local_flags))
diff --git a/src/eval.c b/src/eval.c
index e5dba1b888f..8a6d0d3ff54 100644
--- a/src/eval.c
+++ b/src/eval.c
@@ -2641,6 +2641,8 @@ call6 (fn, arg1, arg2, arg3, arg4, arg5, arg6)
 #endif /* not NO_ARG_ARRAY */
 }
 
+/* The caller should GCPRO all the elements of ARGS.  */
+
 DEFUN ("funcall", Ffuncall, Sfuncall, 1, MANY, 0,
        doc: /* Call first argument as a function, passing remaining arguments to it.
 Return the value that function returns.