X-Git-Url: https://git.distorted.org.uk/~mdw/sod/blobdiff_plain/6e26f47b940265ad1338c642b78fcb3447b0b355..684d95c7eb6ec755d38efacbc377e9e60ba7044e:/doc/clang.tex

diff --git a/doc/clang.tex b/doc/clang.tex
index aebc94d..de9e8df 100644
--- a/doc/clang.tex
+++ b/doc/clang.tex
@@ -53,7 +53,7 @@ The class hierarchy is shown in~\xref{fig:codegen.c-types.classes}.
         @|c-keyword-function-type|                            \-
   \end{tabbing}}
   \caption{Classes representing C types}
-\label{fig:codegen.c-types.classes}
+  \label{fig:codegen.c-types.classes}
 \end{figure}
 
 C type objects are immutable unless otherwise specified.
@@ -181,6 +181,11 @@ type specifier.  Type specifiers fit into two syntactic categories.
   into.
 \end{describe}
 
+\begin{describe}{cty}{lisp @<form>^*}
+  Evaluates the @<form>s as an implicit @|progn|, and returns the value(s) of
+  the final @<form> as a C type.
+\end{describe}
+
 \begin{describe}{gf}
     {print-c-type @<stream> @<type> \&optional @<colon> @<atsign>}
   Print the C type object @<type> to @<stream> in S-expression form.  The
@@ -193,6 +198,28 @@ type specifier.  Type specifiers fit into two syntactic categories.
   default method.
 \end{describe}
 
+\begin{describe*}
+    {\dhead{sym}{c-type}
+     \dhead{meth}{symbol,(eql 'c-type)}
+                 {documentation (@<symbol> symbol)
+                                (@<doc-type> (eql 'c-type))}
+     \dhead{meth}{symbol,(eql 'c-type)}
+                 {setf \=(documentation (@<symbol> symbol)
+                                        (@<doc-type> (eql 'c-type))) \\
+                       \>@<string>}}
+\end{describe*}
+
+\begin{describe*}
+    {\dhead{sym}{c-type-form}
+     \dhead{meth}{symbol,(eql 'c-type-form)}
+                 {documentation (@<symbol> symbol)
+                                (@<doc-type> (eql 'c-type-form))}
+     \dhead{meth}{symbol,(eql 'c-type-form)}
+                 {setf \=(documentation (@<symbol> symbol)
+                                        (@<doc-type> (eql 'c-type-form))) \\
+                       \>@<string>}}
+\end{describe*}
+
 
 \subsection{Comparing C types} \label{sec:clang.c-types.cmp}
 
@@ -407,16 +434,18 @@ Every Lisp keyword is potentially a storage specifier, which simply maps to
 its lower-case print name in C; but other storage specifiers may be more
 complicated objects.
 
-\begin{describe}{cls}
-    {c-storage-specifiers-type (c-type) \&key :subtype :specifiers}
+\begin{describe*}
+    {\dhead{cls}{c-storage-specifiers-type (c-type)
+                                           \&key :subtype :specifiers}
+     \dhead{cty}{specs @<subtype> @<specifier>^*}}
   A type which carries storage specifiers.  The @<subtype> is the actual
   type, and may be any C type; the @<specifiers> are a list of
   storage-specifier objects.
 
-  The type specifier @|(specs @<subtype> @<specifier>^*)| wraps the
-  @<subtype> in a @|c-storage-specifiers-type|, carrying the @<specifier>s,
-  which are a list of storage specifiers in S-expression notation.
-\end{describe}
+  The type specifier @|specs| wraps the @<subtype> in a
+  @|c-storage-specifiers-type|, carrying the @<specifier>s, which are a list
+  of storage specifiers in S-expression notation.
+\end{describe*}
 
 \begin{describe}{fun}{c-type-specifiers @<type> @> @<list>}
   Returns the list of type specifiers attached to the @<type> object, which
@@ -454,7 +483,13 @@ complicated objects.
   @|(c-type (specs @<subtype> (@<head> . @<tail>)))|.
 \end{describe}
 
+\begin{describe}{cstg}{lisp @<form>^*}
+  Evaluates the @<form>s as an implicit @|progn|, and returns the value(s) of
+  the final @<form> as a storage-specifier.
+\end{describe}
+
 \begin{describe}{gf}{pprint-c-storage-specifier @<spec> @<stream>}
+  Prints the storage-specifier @<spec> to @<stream>, in C syntax.
 \end{describe}
 
 \begin{describe}{gf}
@@ -474,14 +509,16 @@ complicated objects.
   @<base-type>.
 \end{describe}
 
-\begin{describe}{cls}{alignas-storage-specifier () \&key :alignment}
-  The class of @|_Alignas| storage specifiers; an instance denotes the
-  specifier @|_Alignas(@<alignment>)|.  The @<alignment> parameter may be any
-  printable object, but is usually a string or C fragment.
-
-  The storage specifier form @|(alignas @<alignment>)| returns a storage
-  specifier @|_Alignas(@<alignment>)|, where @<alignment> is evaluated.
-\end{describe}
+\begin{describe*}
+    {\dhead{cls}{alignas-storage-specifier () \&key :alignment}
+     \dhead{cstg}{alignas @<alignment>}}
+  The class of \mbox{@|_Alignas|} storage specifiers; an instance denotes the
+  specifier \mbox{@|_Alignas(@<alignment>)|}.  The @<alignment> parameter may
+  be any printable object, but is usually a string or C fragment.
+
+  The storage specifier form @|alignas| returns a storage specifier
+  \mbox{@|_Alignas(@<alignment>)|}, where @<alignment> is evaluated.
+\end{describe*}
 
 
 \subsection{Leaf types} \label{sec:clang.c-types.leaf}
@@ -508,15 +545,21 @@ In Sod, the leaf types are
   Two simple type objects are equal if and only if they have @|string=| names
   and matching qualifiers.
 
-  \def\x#1{\desclabel{const}{c-type-#1}}
-  \x{bool} \x{char} \x{wchar-t} \x{signed-char} \x{unsigned-char} \x{short}
-  \x{unsigned-short} \x{int} \x{unsigned} \x{long} \x{unsigned-long}
-  \x{long-long} \x{unsigned-long-long} \x{size-t} \x{ptrdiff-t} \x{float}
-  \x{double} \x{long-double} \x{float-imaginary} \x{double-imaginary}
-  \x{long-double-imaginary} \x{float-complex} \x{double-complex}
-  \x{long-double-complex} \x{va-list} \x{void}
-  \crossproduct\x{{{int}{uint}}{{}{-least}{-fast}}{{8}{16}{32}{64}}{{-t}}}
-  \crossproduct\x{{{int}{uint}}{{ptr}{max}}{{-t}}}
+  \def\x#1{\desclabel{cty}{#1}}
+  \def\y#1{\desclabel{const}{c-type-#1}\x{#1}}
+  \y{bool} \y{wchar-t}
+  \y{int} \x{signed} \y{unsigned} \y{signed-char}
+  \crossproduct\y{{{}{unsigned-}}{{char}{short}{long}{long-long}}}
+  \crossproduct\x{{{}{signed-}{unsigned-}}{{short}{long}{long-long}}{{-int}}}
+  \crossproduct\x{{{signed-}{unsigned-}}{{int}}}
+  \crossproduct\x{{{signed-}}{{short}{int}{long}{long-long}}}
+  \crossproduct\x{{{s}{u}}{{char}{short}{int}{long}{llong}}} \x{llong}
+  \y{size-t} \y{ptrdiff-t} \y{float}
+  \y{double} \y{long-double} \y{float-imaginary} \y{double-imaginary}
+  \y{long-double-imaginary} \y{float-complex} \y{double-complex}
+  \y{long-double-complex} \y{va-list} \y{void}
+  \crossproduct\y{{{int}{uint}}{{}{-least}{-fast}}{{8}{16}{32}{64}}{{-t}}}
+  \crossproduct\y{{{int}{uint}}{{ptr}{max}}{{-t}}}
 
   A number of symbolic type specifiers for builtin types are predefined as
   shown in \xref{tab:codegen.c-types.simple}.  These are all defined as if by
@@ -665,14 +708,15 @@ In Sod, the leaf types are
   type class as a symbol.
 \end{describe}
 
-\begin{describe}{cls}{c-enum-type (tagged-c-type) \&key :qualifiers :tag}
+\begin{describe*}
+    {\dhead{cls}{c-enum-type (tagged-c-type) \&key :qualifiers :tag}
+     \dhead{cty}{enum @<tag> @<qualifier>^*}}
   Represents a C enumerated type.  An instance denotes the C type @|enum|
   @<tag>.  See the direct superclass @|tagged-c-type| for details.
 
-  The type specifier @|(enum @<tag> @<qualifier>^*)| returns the (unique
-  interned) enumerated type with the given @<tag> and @<qualifier>s (all
-  evaluated).
-\end{describe}
+  The type specifier @|enum| returns the (unique interned) enumerated type
+  with the given @<tag> and @<qualifier>s (all evaluated).
+\end{describe*}
 
 \begin{describe}{fun}
     {make-enum-type @<tag> \&optional @<qualifiers> @> @<c-enum-type>}
@@ -681,14 +725,15 @@ In Sod, the leaf types are
   keywords).
 \end{describe}
 
-\begin{describe}{cls}{c-struct-type (tagged-c-type) \&key :qualifiers :tag}
+\begin{describe*}
+    {\dhead{cls}{c-struct-type (tagged-c-type) \&key :qualifiers :tag}
+     \dhead{cty}{struct @<tag> @<qualifier>^*}}
   Represents a C structured type.  An instance denotes the C type @|struct|
   @<tag>.  See the direct superclass @|tagged-c-type| for details.
 
-  The type specifier @|(struct @<tag> @<qualifier>^*)| returns the (unique
-  interned) structured type with the given @<tag> and @<qualifier>s (all
-  evaluated).
-\end{describe}
+  The type specifier @|struct| returns the (unique interned) structured type
+  with the given @<tag> and @<qualifier>s (all evaluated).
+\end{describe*}
 
 \begin{describe}{fun}
     {make-struct-type @<tag> \&optional @<qualifiers> @> @<c-struct-type>}
@@ -697,15 +742,17 @@ In Sod, the leaf types are
   keywords).
 \end{describe}
 
-\begin{describe}{cls}{c-union-type (tagged-c-type) \&key :qualifiers :tag}
+\begin{describe*}
+    {\dhead{cls}{c-union-type (tagged-c-type) \&key :qualifiers :tag}
+     \dhead{cty}{union @<tag> @<qualifier>^*}}
   Represents a C union type.  An instance denotes the C type @|union|
   @<tag>.  See the direct superclass @|tagged-c-type|
   for details.
 
-  The type specifier @|(union @<tag> @<qualifier>^*)| returns the (unique
-  interned) union type with the given @<tag> and @<qualifier>s (all
-  evaluated).
-\end{describe}
+  The type specifier @|union| returns the (unique interned) union type with
+  the given @<tag> and @<qualifier>s (all evaluated).
+\end{describe*}
+
 \begin{describe}{fun}
     {make-union-type @<tag> \&optional @<qualifiers> @> @<c-union-type>}
   Return the (unique interned) C type object for the union C type whose tag
@@ -733,8 +780,10 @@ underlying type of the object.  Note that, as far as Sod is concerned, atomic
 types are not the same as atomic-qualified types: you must be consistent
 about which you use.
 
-\begin{describe}{cls}
-    {c-atomic-type (qualifiable-c-type) \&key :qualifiers :subtype}
+\begin{describe*}
+    {\dhead{cls}{c-atomic-type (qualifiable-c-type)
+                               \&key :qualifiers :subtype}
+     \dhead{cty}{atomic @<type-spec> @<qualifier>^*}}
   Represents an atomic type.  An instance denotes the C type
   @|_Atomic(@<subtype>)|.
 
@@ -744,11 +793,10 @@ about which you use.
   have matching qualifiers.  It is possible, though probably not useful, to
   have an atomic-qualified atomic type.
 
-  The type specifier @|(atomic @<type-spec> @<qualifier>^*)| returns a type
-  qualified atomic @<subtype>, where @<subtype> is the type specified by
-  @<type-spec> and the @<qualifier>s are qualifier keywords (which are
-  evaluated).
-\end{describe}
+  The type specifier @|atomic| returns a type qualified atomic @<subtype>,
+  where @<subtype> is the type specified by @<type-spec> and the
+  @<qualifier>s are qualifier keywords (which are evaluated).
+\end{describe*}
 
 \begin{describe}{fun}
     {make-atomic-type @<c-type> \&optional @<qualifiers> @> @<c-atomic-type>}
@@ -763,24 +811,29 @@ about which you use.
 Pointers are compound types.  The subtype of a pointer type is the type it
 points to.
 
-\begin{describe}{cls}
-    {c-pointer-type (qualifiable-c-type) \&key :qualifiers :subtype}
+\begin{describe*}
+    {\dhead{cls}{c-pointer-type (qualifiable-c-type)
+                                \&key :qualifiers :subtype}
+     \dhead{cty}{* @<type-spec> @<qualifier>^*}
+     \dhead{cty}{string}
+     \dhead{cty}{const-string}}
   Represents a C pointer type.  An instance denotes the C type @<subtype>
   @|*|@<qualifiers>.
 
   The @<subtype> may be any C type.  Two pointer types are equal if and only
   if their subtypes are equal and they have matching qualifiers.
 
-  The type specifier @|(* @<type-spec> @<qualifier>^*)| returns a type
-  qualified pointer-to-@<subtype>, where @<subtype> is the type specified by
-  @<type-spec> and the @<qualifier>s are qualifier keywords (which are
-  evaluated).  The synonyms @|ptr| and @|pointer| may be used in place of the
-  star @`*'.
+  \desclabel{cty}{ptr}
+  \desclabel{cty}{pointer}
+  The type specifier @|*| returns a type qualified pointer-to-@<subtype>,
+  where @<subtype> is the type specified by @<type-spec> and the
+  @<qualifier>s are qualifier keywords (which are evaluated).  The synonyms
+  @|ptr| and @|pointer| may be used in place of the star @`*'.
 
   The symbol @|string| is a type specifier for the type pointer to
   characters; the symbol @|const-string| is a type specifier for the type
   pointer to constant characters.
-\end{describe}
+\end{describe*}
 
 \begin{describe}{fun}
     {make-pointer-type @<c-type> \&optional @<qualifiers>
@@ -796,7 +849,11 @@ points to.
 Arrays implement the compound-type protocol.  The subtype of an array type is
 the array element type.
 
-\begin{describe}{cls}{c-array-type (c-type) \&key :subtype :dimensions}
+\begin{describe*}
+    {\dhead{cls}{c-array-type (c-type) \&key :subtype :dimensions}
+     \dhead{cty}{[] @<type-spec> @<dimension>^*}}
+  \desclabel{cty}{array}[|(]
+  \desclabel{cty}{vec}[|(]
   Represents a multidimensional C array type.  The @<dimensions> are a list
   of dimension specifiers $d_0$, $d_1$, \ldots, $d_{n-1}$; an instance then
   denotes the C type @<subtype> @|[$d_0$][$d_1$]$\ldots$[$d_{n-1}$]|.  An
@@ -813,12 +870,15 @@ the array element type.
   $d_1$ of \ldots\ arrays of $d_{n-1}$ elements of type @<subtype>.  We shall
   continue to abuse terminology and refer to multidimensional arrays.
 
-  The type specifier @|([] @<type-spec> @<dimension>^*)| constructs a
-  multidimensional array with the given @<dimension>s whose elements have the
-  type specified by @<type-spec>.  If no dimensions are given then a
-  single-dimensional array with unspecified extent.  The synonyms @|array|
-  and @|vector| may be used in place of the brackets @`[]'.
-\end{describe}
+  The type specifier @|[]| constructs a multidimensional array with the given
+  @<dimension>s whose elements have the type specified by @<type-spec>.  If
+  no dimensions are given then a single-dimensional array with unspecified
+  extent.  The synonyms @|array| and @|vec| may be used in place of the
+  brackets @`[]'.
+
+  \desclabel{cty}{array}[|)]
+  \desclabel{cty}{vec}[|)]
+\end{describe*}
 
 \begin{describe}{fun}
     {make-array-type @<subtype> @<dimensions> @> @<c-array-type>}
@@ -910,7 +970,16 @@ function type is the type of the function's return value.
   unchanged.
 \end{describe}
 
-\begin{describe}{cls}{c-function-type (c-type) \&key :subtype :arguments}
+\begin{describe*}
+    {\dhead{cls}{c-function-type (c-type) \&key :subtype :arguments}
+     \dhead*{cty}{fun @<return-type>
+                      @{ (@<arg-name> @<arg-type>) @}^*
+                      @[:ellipsis @! . @<form>@]}}
+  \desclabel{cty}{()}[|(]
+  \desclabel{cty}{fn}[|(]
+  \desclabel{cty}{func}[|(]
+  \desclabel{cty}{function}[|(]
+  \descindex{cty}{fun}[|(]
   Represents C function types.  An instance denotes the type of a C
   function which accepts the @<arguments> and returns @<subtype>.
 
@@ -928,19 +997,13 @@ function type is the type of the function's return value.
   in the same order, and either both or neither argument list ends with
   @|:ellipsis|; argument names are not compared.
 
-  The type specifier
-  \begin{prog}
-    (fun @<return-type>
-         @{ (@<arg-name> @<arg-type>) @}^*
-         @[:ellipsis @! . @<form>@])
-  \end{prog}
-  constructs a function type.  The function has the subtype @<return-type>.
-  The remaining items in the type-specifier list are used to construct the
-  argument list.  The argument items are a possibly improper list, beginning
-  with zero or more \emph{explicit arguments}: two-item
-  @<arg-name>/@<arg-type> lists.  For each such list, an @|argument| object
-  is constructed with the given name (evaluated) and type.  Following the
-  explicit arguments, there may be
+  The type specifier @|fun| constructs a function type.  The function has the
+  subtype @<return-type>.  The remaining items in the type-specifier list are
+  used to construct the argument list.  The argument items are a possibly
+  improper list, beginning with zero or more \emph{explicit arguments}:
+  two-item @<arg-name>/@<arg-type> lists.  For each such list, an @|argument|
+  object is constructed with the given name (evaluated) and type.  Following
+  the explicit arguments, there may be
   \begin{itemize}
   \item nothing, in which case the function's argument list consists only of
     the explicit arguments;
@@ -968,11 +1031,18 @@ function type is the type of the function's return value.
             (ret (c-type-subtype other-func)))                \-\\ \ind
       (c-type (fun \=(lisp ret) ("first" int) . args)
   \end{prog}
-\end{describe}
+  \descindex{cty}{fun}[|)]
+\end{describe*}
 
-\begin{describe}{cls}
-    {c-keyword-function-type (c-function-type)
-      \&key :subtype :arguments :keywords}
+\begin{describe*}
+    {\dhead{cls}{c-keyword-function-type (c-function-type)
+                                         \&key :subtype :arguments :keywords}
+     \dhead{cty}{fun \=@<return-type>
+                       @{ (@<arg-name> @<arg-type>) @}^*      \+\\
+                       @{ \=:keys @{ (@<kw-name> @<kw-type>
+                                      @[@<kw-default>@]) @}^*
+                               @[. @<form>@] @!               \+\\
+                             . @<form> @}}}
   Represents `functions' which accept keyword arguments.  Of course, actual C
   functions can't accept keyword arguments directly, but this type is useful
   for describing messages and methods which deal with keyword arguments.
@@ -998,19 +1068,11 @@ function type is the type of the function's return value.
   arguments accepted by the functions is not significant.
 
   Keyword functions are constructed using an extended version of the @|fun|
-  specifier used for ordinary C function types.  The extended syntax is as
-  follows.
-  \begin{prog}
-    (fun \=@<return-type>
-           @{ (@<arg-name> @<arg-type>) @}^*                  \+\\
-           @{ \=:keys @{ (@<kw-name> @<kw-type> @[@<kw-default>@]) @}^*
-                   @[. @<form>@] @!                           \+\\
-                 . @<form> @}
-  \end{prog}
-  where either the symbol @|:keys| appears literally in the specifier, or the
-  @<form> evaluates to a list containing the symbol @|:keys|.  (If neither of
-  these circumstances obtains, then the specifier constructs an ordinary
-  function type.)
+  specifier (or any of its synonyms) used for ordinary C function types.
+  Either the symbol @|:keys| must appear literally in the specifier, or the
+  @<form> must evaluate to a list containing the symbol @|:keys|.  (If
+  neither of these circumstances obtains, then the specifier constructs an
+  ordinary function type.)
 
   See the description of \descref{cls}{c-function-type} for how a trailing
   @<form> is handled.
@@ -1018,7 +1080,12 @@ function type is the type of the function's return value.
   The list of @<arg-name>s and @<arg-type>s describes the positional
   arguments.  The list of @<kw-name>s, @<kw-type>s and @<kw-defaults>s
   describes the keyword arguments.
-\end{describe}
+
+  \descindex{cty}{()}[|)]
+  \descindex{cty}{fn}[|)]
+  \descindex{cty}{func}[|)]
+  \descindex{cty}{function}[|)]
+\end{describe*}
 
 \begin{describe}{fun}
     {make-function-type @<subtype> @<arguments> @> @<c-function-type>}
@@ -1151,9 +1218,11 @@ function type is the type of the function's return value.
 
 \subsection{Class types} \label{sec:clang.c-types.class}
 
-\begin{describe}{cls}
-    {c-class-type (simple-c-type) \&key :class :tag :qualifiers :name}
-\end{describe}
+\begin{describe*}
+    {\dhead{cls}{c-class-type (simple-c-type)
+                              \&key :class :tag :qualifiers :name}
+     \dhead{cty}{class @<name> @<qualifier>^*}}
+\end{describe*}
 
 \begin{describe*}
     {\dhead{gf}{c-type-class @<class-type> @> @<class>}
@@ -1335,7 +1404,7 @@ Temporary names are represented by objects which implement a simple protocol.
 
 \begin{describe*}
     {\dhead*{cls}{@<code>-inst (inst) \&key \dots}
-     \dhead*{fn}{make-@<code>-inst \dots}
+     \dhead*{fun}{make-@<code>-inst \dots}
      \dhead*{gf}{inst-@<slot> @<inst> @> @<value>}}
   \def\instclass#1#2#3{%
     #1{cls}{#3-inst}[#2]%
