X-Git-Url: https://git.distorted.org.uk/~mdw/sod/blobdiff_plain/020b9e2b4364c61a668d47c4c5405295349817d8..054e8f8f1ea255ff77b19df82bd845e5686dac0d:/doc/clang.tex?ds=inline

diff --git a/doc/clang.tex b/doc/clang.tex
index c4a6a53..b273a2c 100644
--- a/doc/clang.tex
+++ b/doc/clang.tex
@@ -169,12 +169,12 @@ type specifier.  Type specifiers fit into two syntactic categories.
 \begin{describe}{gf}{expand-c-type-spec @<type-spec> @> @<form>}
   Returns the Lisp form that @|(c-type @<type-spec>)| would expand into.
 
-  If @<type-spec> is a list, then \descref{expand-c-type-form}{fun} is
+  If @<type-spec> is a list, then \descref{expand-c-type-form}{gf} is
   invoked.
 \end{describe}
 
 \begin{describe}{gf}{expand-c-type-form @<head> @<tail> @> @<form>}
-  Returns the Lisp form that @|(c-type (@<head> . @<tail>)| would expand
+  Returns the Lisp form that @|(c-type (@<head> . @<tail>))| would expand
   into.
 \end{describe}
 
@@ -565,23 +565,34 @@ In Sod, the leaf types are
 
 \begin{describe}{mac}
     {define-simple-c-type
-       \=@{ @<name> @! (@<name>^+) @} @<string>               \+\\
+       \=@{ @<name> @! (@<name>^+) @}
+         @{ @<string> @! (@<string>^*) @}                     \+\\
          @[[ @|:export| @<export-flag> @]]
       \-\nlret @<name>}
   Define type specifiers for a new simple C type.  Each symbol @<name> is
   defined as a symbolic type specifier for the (unique interned) simple C
-  type whose name is the value of @<string>.  Further, each @<name> is
-  defined to be a type operator: the type specifier @|(@<name>
+  type whose name is the value of (the first) @<string>.  Further, each
+  @<name> is defined to be a type operator: the type specifier @|(@<name>
   @<qualifier>^*)| evaluates to the (unique interned) simple C type whose
-  name is @<string> and which has the @<qualifiers> (which are evaluated).
+  name is (the first) @<string> and which has the @<qualifiers> (which are
+  evaluated).
 
-  Furthermore, a variable @|c-type-@<name>| is defined, for the first @<name>
-  only, and initialized with the newly constructed C type object.
+  Each of the @<string>s is associated with the resulting type for retrieval
+  by \descref{find-simple-c-type}{fun}.  Furthermore, a variable
+  @|c-type-@<name>| is defined, for the first @<name> only, and initialized
+  with the newly constructed C type object.
 
   If @<export-flag> is true, then the @|c-type-@<name>| variable name, and
   all of the @<name>s, are exported from the current package.
 \end{describe}
 
+\begin{describe}{fun}
+    {find-simple-c-type @<string> @> @{ @<simple-c-type> @! @|nil| @}}
+  If @<string> is the name of a simple C type, as established by the
+  \descref{define-simple-c-type}[macro]{mac}, then return the corresponding
+  @|simple-c-type| object; otherwise, return @|nil|.
+\end{describe}
+
 \begin{describe}{cls}{tagged-c-type (qualifiable-c-type)
     \&key :qualifiers :tag}
   Provides common behaviour for C tagged types.  A @<tag> is a string
@@ -1006,23 +1017,45 @@ function type is the type of the function's return value.
   original list is not modified, but may share structure with the new list.
 \end{describe}
 
-\begin{describe}{fun}{merge-keyword-lists @<lists> @> @<list>}
+\begin{describe}{fun}
+    {merge-keyword-lists @<what-function> @<lists> @> @<list>}
   Merge a number of keyword-argument lists together and return the result.
 
-  The @<lists> parameter is a list consisting of a number of @|(@<args>
-  . @<origin>)| pairs: in each pair, @<args> is a list of
-  \descref{argument}{cls} objects, and @<origin> is either nil or an object
-  whose printed representation describes the origin of the corresponding
-  @<args> list, suitable for inclusion in an error message.
+  The @<what-function> is either nil or a function designator; see below.
+
+  The @<lists> parameter is a list consisting of a number of
+  @|(@<report-function> . @<args>)| pairs: in each pair, @<report-function>
+  is either nil or a function designator, and @<args> is a list of
+  \descref{argument}{cls} objects.
 
   The resulting list contains exactly one argument for each distinct argument
   name appearing in the input @<lists>; this argument will contain the
   default value from the earliest occurrence in the input @<lists> of an
   argument with that name.
 
-  If the same name appears multiple times with different types, an error is
-  signalled quoting the name, conflicting types, and (if non-nil) the origins
-  of the offending argument objects.
+  If the same name appears multiple times with different types, a continuable
+  error will be signalled, and one of the conflicting argument types will be
+  chosen arbitrarily.  The @<what-function> will be called to establish
+  information which will be reported to the user.  It will be called with no
+  arguments and is expected to return two values:
+  \begin{itemize}
+  \item a file location @<floc> or other object acceptable to
+    \descref{file-location}{gf}, to be used as the location of the main
+    error; and
+  \item an object @<what>, whose printed representation should be a noun
+    phrase describing the object for which the argument lists are being
+    combined.
+  \end{itemize}
+  The phrasing of the error message is `type mismatch in @<what>'.  Either,
+  or both, of @<floc> and @<what> may be nil, though this is considered poor
+  practice; if @<what-function> is nil, this is equivalent to a function
+  which returns two nil values.  Following the error, the @<report-function>s
+  for the @<args> lists containing the conflicting argument objects are
+  called, in an arbitrary order, with a single argument which is the
+  offending @|argument| object; the function is expected to issue information
+  messages (see \descref{info}{fun}) to give more detail for diagnosing the
+  conflict.  If a @<report-function> is nil, then nothing happens; this is
+  considered poor practice.
 \end{describe}
 
 \begin{describe}{fun}
