From 781a8fbd66088ce2eb16776fd951f8b79732d69c Mon Sep 17 00:00:00 2001
From: Mark Wooding <mdw@distorted.org.uk>
Date: Sat, 7 May 2016 15:32:51 +0100
Subject: [PATCH] doc/: Miscellaneous clarifications and rewordings.

---
 doc/concepts.tex | 27 ++++++++++++++++++---------
 doc/runtime.tex  | 19 ++++++++-----------
 2 files changed, 26 insertions(+), 20 deletions(-)

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
diff --git a/doc/runtime.tex b/doc/runtime.tex
index f6f0846..4178c43 100644
--- a/doc/runtime.tex
+++ b/doc/runtime.tex
@@ -183,7 +183,7 @@ The following keyword-argument macros can be used within the @|KWARGS|
 A \emph{keyword set} defines the collection of keyword arguments accepted by
 a particular function.  The same keyword set may be used by several
 functions.  (If your function currently accepts no keyword arguments, but you
-plan to add some later, do not define a keyword set, and use the
+plan to add some later, do not define a keyword set; instead, use the
 @|KWPARSE_EMPTY| macro described below.)
 
 Each keyword set has a name, which is a C identifier.  It's good to choose
@@ -196,15 +196,12 @@ the same name as the function.
 
 The keyword arguments for a keyword set named @<set> are described by a `list
 macro' named @|@<set>{}_KWSET|.  This macro takes a single argument,
-conventionally named @`_'.
-
-It should expand to a sequence of one or more list items of the form
+conventionally named @`_'.  It should expand to a sequence of one or more
+list items of the form
 \begin{prog}
   _(@<type>, @<name>, @<default>)
 \end{prog}
-with no separation between them.
-
-For example:
+with no separation between them.  For example:
 \begin{prog}
   \#define example_KWSET(_) @\\ \\ \ind
     _(int, x, 0) @\\ \\
@@ -276,10 +273,10 @@ keyword arguments.
     {@<declaration-specifiers> KWDECL(@<set>, @<kw>);}
   The macro declares and initializes a keyword argument structure variable
   named @<kw> for the named keyword @<set>.  The optional
-  @<declaration-specifiers> may provide additional storage-class, qualifiers,
-  or other declaration specifiers.  The @`_suppliedp' flags are initialized
-  to zero; the other members are initialized with the corresponding defaults
-  from the keyword-set definition.
+  @<declaration-specifiers> may provide additional storage-class specifiers,
+  qualifiers, or other declaration specifiers.  The @`_suppliedp' flags are
+  initialized to zero; the other members are initialized with the
+  corresponding defaults from the keyword-set definition.
 \end{describe}
 
 \begin{describe}[KWSET_PARSEFN]{mac}
-- 
2.11.0

