# HG changeset patch
# User Paul Boddie <paul@boddie.org.uk>
# Date 1385685505 -3600
# Node ID 28ed9334c86108c1cd857721c52201b3fe4ab971
# Parent  bebf059c7be66b86dfc7ea4cfb153d69c820cb8a
Added more notes about invocation, particularly around dynamic function contexts
and their presence in method invocations.

diff -r bebf059c7be6 -r 28ed9334c861 docs/invocation.txt
--- a/docs/invocation.txt	Fri Nov 29 01:37:15 2013 +0100
+++ b/docs/invocation.txt	Fri Nov 29 01:38:25 2013 +0100
@@ -212,6 +212,18 @@
         -> load context for argument #1 (f, since an instance is referenced)
     obj -> argument #2
 
+Dynamic default information and methods:
+
+  class C:
+    def f(self, y=nonconst):
+      ...
+
+  Defines additional context for the method:
+
+    class C:
+      def f(<context>, self, y=nonconst):
+        ...
+
 Functions as methods:
 
   def f(x, y, z): ...
diff -r bebf059c7be6 -r 28ed9334c861 docs/syspython.txt
--- a/docs/syspython.txt	Fri Nov 29 01:37:15 2013 +0100
+++ b/docs/syspython.txt	Fri Nov 29 01:38:25 2013 +0100
@@ -23,14 +23,32 @@
 or method. Note that the apply function resembles the Python function of the
 same name but is not actually that particular function.
 
+    apply(fn, ...)                  # general invocation
+
 A family of special functions for invocations exists, addressing optimisation
 situations identified by program analysis:
 
-    apply               # general invocation
-    applyclass          # direct invocation of an instantiator
-    applyfunction       # function-specific invocation
-    applystaticmethod   # specific invocation of a method via a class
-    applymethod         # specific invocation of a method via self
+    applyclass(cls, ...)            # direct invocation of an instantiator
+    applyfunction(fn, ...)          # function-specific invocation
+    applystaticmethod(fn, obj, ...) # specific invocation of a method via a class
+    applymethod(fn, obj, ...)       # specific invocation of a method via self
+
+Where dynamic functions are to be invoked, the context providing the defaults
+needs to be supplied to the function or method, but this can be done using the
+above special functions as follows:
+
+    applyclass(cls, __context__, ...)
+    applyfunction(fn, __context__, ...)
+    applystaticmethod(fn, __context__, obj, ...)
+    applymethod(fn, __context__, obj, ...)
+
+Where optimisation possibilities cannot be identified in advance, the apply
+function must deal with the following aspects of invocation:
+
+  * Whether a context argument is required
+  * Whether a dynamic function is being invoked, thus requiring a context for
+    access to defaults
+  * Whether an appropriate number of arguments have been provided
 
 Low-Level Code
 --------------