Internal doc fixes for duk_activation changes

doc/execution.rst

@@ -63,8 +63,8 @@ changes:
 
 * A setjmp catchpoint is needed for protected calls.
 
-* The call stack is resized if necessary, and an activation record
+* An activation record, ``duk_activation``, is allocated and set up for the
-  (``duk_activation``) is set up for the new call.
+  new call.
 
 * The value stack is resized if necessary, and a fresh value stack frame
   is established for the call.  The calling value stack frame and the target
@@ -380,7 +380,7 @@ Misc notes
 
 * The value stack doesn't hold all the internal state relevant for an
   activation.  Some state, such as active environment records (``lex_env``
-  and ``var_env``) are held in the ``duk_activation`` call stack structure.
+  and ``var_env``) are held in the ``duk_activation`` activation structure.
 
 Value stack management
 ======================

doc/memory-management.rst

@@ -403,7 +403,7 @@ ownership relationships::
            |
            +-->  value stack
            |
-           +-->  call stack -->  duk_activations (array)
+           +-->  call stack -->  duk_activations (linked list)
            |                       |
            |                       `--> duk_catchers (linked list)
            |

doc/side-effects.rst

@@ -71,11 +71,12 @@ The most extensive type of side effect is arbitrary code execution, caused
 by e.g. a finalizer or a Proxy trap call (and a number of indirect causes).
 The potential side effects are very wide:
 
-* Because a call is made, value stacks and call stacks may be grown (but
+* Because a call is made, the value stack may be grown (but not shrunk) and
-  not shrunk) and their base pointers may change.  As a result, any duk_tval
+  its base pointer may change.  As a result, any duk_tval pointers to the
-  pointers to the value stack and duk_activation pointers to the call stack
+  value stack are (potentially) invalidated.  Since Duktape 2.2 duk_activation
-  are (potentially) invalidated.  Since Duktape 2.2 duk_catchers are separately
+  and duk_catcher structs are allocated separately and have a stable pointer.
-  allocated and have a stable pointer.
+  Before Duktape 2.2 duk_activations were held in a call stack and duk_catchers
+  in a catch stack, and their pointers might be invalidated by side effects.
 
 * An error throw may happen, clobbering heap longjmp state.  This is a
   problem particularly in error handling where we're dealing with a previous
@@ -154,10 +155,10 @@ Other side effects don't happen with current mark-and-sweep implementation.
 For example, the following don't happen (but could, if mark-and-sweep scope
 and side effect lockouts are changed):
 
-* Thread value stack and call stack are never reallocated and all pointers to
+* Thread value stack is never reallocated and all pointers to duk_tvals remain
-  duk_tvals and duk_activations remain valid; duk_catcher pointers are stable
+  valid; duk_activation and duk_catcher pointers are stable in Duktape 2.2.
-  in Duktape 2.2.  (This could easily change if mark-and-sweep were to "compact"
+  (This could easily change if mark-and-sweep were to "compact" the value stack
-  the stacks in an emergency GC.)
+  in an emergency GC.)
 
 The mark-and-sweep side effects listed above are not fundamental to the
 engine and could be removed if they became inconvenient.  For example, it's