X-Git-Url: https://git.distorted.org.uk/~mdw/sod/blobdiff_plain/14adef2f3c2a0a80be0ca2e1a364256812203bd8..054e8f8f1ea255ff77b19df82bd845e5686dac0d:/doc/clang.tex diff --git a/doc/clang.tex b/doc/clang.tex index ebe9d4e..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 @ @> @
} Returns the Lisp form that @|(c-type @)| would expand into. - If @ is a list, then \descref{expand-c-type-form}{fun} is + If @ is a list, then \descref{expand-c-type-form}{gf} is invoked. \end{describe} \begin{describe}{gf}{expand-c-type-form @ @ @> @} - Returns the Lisp form that @|(c-type (@ . @)| would expand + Returns the Lisp form that @|(c-type (@ . @))| would expand into. \end{describe} @@ -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 @ @> @} +\begin{describe}{fun} + {merge-keyword-lists @ @ @> @} Merge a number of keyword-argument lists together and return the result. - The @ parameter is a list consisting of a number of @|(@ - . @)| pairs: in each pair, @ is a list of - \descref{argument}{cls} objects, and @ is either nil or an object - whose printed representation describes the origin of the corresponding - @ list, suitable for inclusion in an error message. + The @ is either nil or a function designator; see below. + + The @ parameter is a list consisting of a number of + @|(@ . @)| pairs: in each pair, @ + is either nil or a function designator, and @ is a list of + \descref{argument}{cls} objects. The resulting list contains exactly one argument for each distinct argument name appearing in the input @; this argument will contain the default value from the earliest occurrence in the input @ 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 @ 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 @ or other object acceptable to + \descref{file-location}{gf}, to be used as the location of the main + error; and + \item an object @, 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 @'. Either, + or both, of @ and @ may be nil, though this is considered poor + practice; if @ is nil, this is equivalent to a function + which returns two nil values. Following the error, the @s + for the @ 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 @ is nil, then nothing happens; this is + considered poor practice. \end{describe} \begin{describe}{fun}