From: Mark Wooding Date: Sat, 7 May 2016 14:32:51 +0000 (+0100) Subject: doc/: Miscellaneous clarifications and rewordings. X-Git-Url: http://www.chiark.greenend.org.uk/ucgi/~mdw/git/sod/commitdiff_plain/781a8fbd66088ce2eb16776fd951f8b79732d69c doc/: Miscellaneous clarifications and rewordings. --- 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 @ are described by a `list macro' named @|@{}_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} _(@, @, @) \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. {@ KWDECL(@, @);} The macro declares and initializes a keyword argument structure variable named @ for the named keyword @. The optional - @ 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. + @ 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}