\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}
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}
~mdw / sod / blobdiff