X-Git-Url: http://www.chiark.greenend.org.uk/ucgi/~mdw/git/sod/blobdiff_plain/9761db0da830385bcc0fca81f56f24536a46aeda..781a8fbd66088ce2eb16776fd951f8b79732d69c:/doc/concepts.tex

diff --git a/doc/concepts.tex b/doc/concepts.tex
index b8cdfe9..1a84b88 100644
--- a/doc/concepts.tex
+++ b/doc/concepts.tex
@@ -195,7 +195,7 @@ It works as follows.
   earliest position in these candidate merges at which they disagree.  The
   \emph{candidate classes} at this position are the classes appearing at this
   position in the candidate merges.  Each candidate class must be a
-  superclass of exactly one of $C$'s direct superclasses, since otherwise the
+  superclass of distinct direct superclasses of $C$, since otherwise the
   candidates would be ordered by their common subclass's class precedence
   list.  The class precedence list contains, at this position, that candidate
   class whose subclass appears earliest in $C$'s local precedence order.
@@ -208,8 +208,8 @@ a link superclass, and the link superclass of a class $C$, if it exists, need
 not be a direct superclass of $C$.
 
 Superclass links must obey the following rule: if $C$ is a class, then there
-must be no three superclasses $X$, $Y$ and~$Z$ of $C$ such that both $Z$ is
-the link superclass of both $X$ and $Y$.  As a consequence of this rule, the
+must be no three superclasses $X$, $Y$ and~$Z$ of $C$ such that $Z$ is the
+link superclass of both $X$ and $Y$.  As a consequence of this rule, the
 superclasses of $C$ can be partitioned into linear \emph{chains}, such that
 superclasses $A$ and $B$ are in the same chain if and only if one can trace a
 path from $A$ to $B$ by following superclass links, or \emph{vice versa}.
@@ -251,7 +251,7 @@ sets the slots of a \emph{direct} instance of the class to the correct
 initial values.  If several of $C$'s superclasses define initializers for the
 same slot then the initializer from the most specific such class is used.  If
 none of $C$'s superclasses define an initializer for some slot then that slot
-will not be initialized.
+will be left uninitialized.
 
 The initializer for a slot with scalar type may be any C expression.  The
 initializer for a slot with aggregate type must contain only constant
@@ -413,7 +413,8 @@ There are three main cases to distinguish.
   conversion can fail: the object in question might not be an instance of~$B$
   at all.  The macro \descref{SOD_CONVERT}{mac} and the function
   \descref{sod_convert}{fun} perform general conversions.  They return a null
-  pointer if the conversion fails.
+  pointer if the conversion fails.  (There are therefore your analogue to the
+  \Cplusplus @|dynamic_cast<>| operator.)
 \end{itemize}
 The Sod translator generates macros for performing both in-chain and
 cross-chain upcasts.  For each class~$C$, and each proper superclass~$B$
@@ -576,10 +577,13 @@ follows.
   returns; otherwise the behaviour of @|next_method| is to invoke the before
   methods (if any), followed by the most specific primary method, followed by
   the @|around| methods (if any), and to return whichever value was returned
-  by the most specific primary method.  That is, the behaviour of the least
-  specific @|around| method's @|next_method| function is exactly the
-  behaviour that the effective method would have if there were no @|around|
-  methods.
+  by the most specific primary method, as described in the following items.
+  That is, the behaviour of the least specific @|around| method's
+  @|next_method| function is exactly the behaviour that the effective method
+  would have if there were no @|around| methods.  Note that if the
+  least-specific @|around| method calls its @|next_method| more than once
+  then the whole sequence of @|before|, primary, and @|after| methods occurs
+  multiple times.
 
   The value returned by the most specific @|around| method is the value
   returned by the effective method.
@@ -634,6 +638,11 @@ arguments.  If the method body has overwritten its formal arguments, then
 @|CALL_NEXT_METHOD| will pass along the updated values, rather than the
 original ones.
 
+A primary or @|around| method which invokes its @|next_method| function is
+said to \emph{extend} the message behaviour; a method which does not invoke
+its @|next_method| is said to \emph{override} the behaviour.  Note that a
+method may make a decision to override or extend at runtime.
+
 \subsubsection{Aggregating method combinations}
 A number of other method combinations are provided.  They are called
 `aggregating' method combinations because, instead of invoking just the most