doc/concepts.tex: Typeset method rôle names as identifiers.

[sod] / doc / clang.tex

diff --git a/doc/clang.tex b/doc/clang.tex
index ebe9d4e2db069cede474b2fcf0ff1edd9531a93c..6d256ec4940a44a181aefcfdc97c3413a1add527 100644 (file)
--- a/doc/clang.tex
+++ b/doc/clang.tex
@@ -1017,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}