-/* Used in a symbol value cell when the symbol's value is per-buffer.
- The actual contents resemble a cons cell which starts a list like this:
- (REALVALUE BUFFER CURRENT-ALIST-ELEMENT . DEFAULT-VALUE).
-
- The cons-like structure is for historical reasons; it might be better
- to just put these elements into the struct, now.
-
- BUFFER is the last buffer for which this symbol's value was
- made up to date.
-
- CURRENT-ALIST-ELEMENT is a pointer to an element of BUFFER's
- local_var_alist, that being the element whose car is this
- variable. Or it can be a pointer to the
- (CURRENT-ALIST-ELEMENT . DEFAULT-VALUE),
- if BUFFER does not have an element in its alist for this
- variable (that is, if BUFFER sees the default value of this
- variable).
-
- If we want to examine or set the value and BUFFER is current,
- we just examine or set REALVALUE. If BUFFER is not current, we
- store the current REALVALUE value into CURRENT-ALIST-ELEMENT,
- then find the appropriate alist element for the buffer now
- current and set up CURRENT-ALIST-ELEMENT. Then we set
- REALVALUE out of that element, and store into BUFFER.
-
- If we are setting the variable and the current buffer does not
- have an alist entry for this variable, an alist entry is
- created.
-
- Note that REALVALUE can be a forwarding pointer. Each time it
- is examined or set, forwarding must be done. Each time we
- switch buffers, buffer-local variables which forward into C
- variables are swapped immediately, so the C code can assume
- that they are always up to date.
+/* struct Lisp_Buffer_Local_Value is used in a symbol value cell when
+ the symbol has buffer-local or frame-local bindings. (Exception:
+ some buffer-local variables are built-in, with their values stored
+ in the buffer structure itself. They are handled differently,
+ using struct Lisp_Buffer_Objfwd.)
+
+ The `realvalue' slot holds the variable's current value, or a
+ forwarding pointer to where that value is kept. This value is the
+ one that corresponds to the loaded binding. To read or set the
+ variable, you must first make sure the right binding is loaded;
+ then you can access the value in (or through) `realvalue'.
+
+ `buffer' and `frame' are the buffer and frame for which the loaded
+ binding was found. If those have changed, to make sure the right
+ binding is loaded it is necessary to find which binding goes with
+ the current buffer and selected frame, then load it. To load it,
+ first unload the previous binding, then copy the value of the new
+ binding into `realvalue' (or through it). Also update
+ LOADED-BINDING to point to the newly loaded binding.