r1534: *** empty log message ***

diff --git a/ChangeLog b/ChangeLog
index 6ed9d594e2b15791dd56bd1367141b306fbe39b2..ab61ff2029872a792473eb943405e65bcae8ec6a 100644 (file)
--- a/ChangeLog
+++ b/ChangeLog
@@ -1,4 +1,6 @@
 9 Mar 2002
+
+       * Added to documentation
        
        * Made Allegro CL array access more efficient
        

diff --git a/doc/intro.sgml b/doc/intro.sgml
index a42cc8d1d4ec744a0f18598bd9ac76209ce536c8..d432b9f218ff03fa9f237913cd45e99046046c56 100644 (file)
--- a/doc/intro.sgml
+++ b/doc/intro.sgml
@@ -58,7 +58,7 @@
       directory containing &uffi; into
       <varname>mk:*central-registry*</varname>. Whenever you
 want to load the &uffi; package, use the function
-      <computeroutput>(mk:oos :uffi 'load)</computeroutput>.
+      <computeroutput>(mk:load-system :uffi)</computeroutput>.
     </para>
   </sect1>
 </chapter>

diff --git a/doc/ref.sgml b/doc/ref.sgml
index 5eb4f9e673ae59d1b9c317a43ea1e7dd0fa89ff1..0bc5b4762013d694097ca3a229b0a3064d8a21f8 100644 (file)
--- a/doc/ref.sgml
+++ b/doc/ref.sgml
@@ -62,12 +62,74 @@
 
     <sect1>
       <title>Immediate Types</title>
+      <sect2>
+       <title>Overview</title>
+       <para>
+         Immediate types have a single value, these include
+         characters, numbers, and pointers. They are all symbols in
+         the keyword package.
+       </para>
+       <itemizedlist>
+         <listitem>
+           <para><constant>:byte</constant> - Unsigned 8-bit</para>
+         </listitem>
+         <listitem>
+           <para><constant>:char</constant> - Signed 8-bits</para>
+         </listitem>
+         <listitem>
+           <para><constant>:unsigned-char</constant> - Unsigned 8-bits</para>
+         </listitem>
+         <listitem>
+           <para><constant>:short</constant> - Signed 16-bits</para>
+         </listitem>
+         <listitem>
+           <para><constant>:unsigned-short</constant> - Unsigned 16-bits</para>
+         </listitem>
+         <listitem>
+           <para><constant>:int</constant> - Signed 32-bits</para>
+         </listitem>
+         <listitem>
+           <para><constant>:unsigned-int</constant> - Unsigned 32-bits</para>
+         </listitem>
+         <listitem>
+           <para><constant>:long</constant> - Signed 32-bits</para>
+         </listitem>
+         <listitem>
+           <para><constant>:unsigned-long</constant> - Unsigned 32-bits</para>
+         </listitem>
+         <listitem>
+           <para><constant>:single-float</constant> - 32-bit floating point</para>
+         </listitem>
+         <listitem>
+           <para><constant>:double-float</constant> - 64-bit floating point</para>
+         </listitem>
+         <listitem>
+           <para>
+             <constant>
+               :cstring
+             </constant> 
+             - A null-terminated string used for passing and returning with a function.
+             </para>
+         </listitem>
+         <listitem>
+           <para>
+             <constant>
+               :void
+             </constant> 
+             - An absence of a value. Used in generic pointers and in
+             return types from functions.</para>
+         </listitem>
+         <listitem>
+           <para><constant>*</constant> - Used to declare a pointer to an object</para>
+         </listitem>
+       </itemizedlist>
+      </sect2>
       <sect2>
        <title>def-constant</title>
        <para>
          This is a thin wrapper around
-         <function>defconstant</function>. It also exports the symbol
-         from the package.
+         <function>defconstant</function>. It evaluates at
+           compile-time and exports the symbol from the package.
        </para>
       </sect2>
       <sect2>
@@ -75,6 +137,16 @@
        <para>
          This is the main function for creating new types.
        </para>
+       <sect3>
+         <title>Examples</title>
+         <para>
+           <programlisting>
+(def-type my-generic-pointer (* :void))
+(def-type a-double-float :double-float)
+(def-type char-ptr (* :char))
+           </programlisting>
+         </para>
+       </sect3>
       </sect2>
       <sect2>
        <title>null-char-p</title>
@@ -96,8 +168,18 @@
       <sect2>
        <title>def-struct</title>
        <para>
-         Declares a structure.
+         Declares a structure. A special type is available as a slot in the field. It is
+         a pointer that points to an instance of the parent structure. It's type is
+         <constant>:pointer-self</constant>.
        </para>
+       <sect3>
+         <title>Examples</title>
+         <para>
+           <programlisting>
+(def-struct foo (a :unsigned-int) (b :array 10) (next :pointer-self))
+           </programlisting>
+         </para>
+       </sect3>
       </sect2>
       <sect2 id="get-slot-value">
        <title>get-slot-value</title>
@@ -131,7 +213,7 @@
       <sect2>
        <title>allocate-foreign-object</title>
        <para>
-         Allocates an instance of a foreign object.
+         Allocates an instance of a foreign object. It returns a pointer to the object.
        </para>
       </sect2>
       <sect2>
@@ -167,13 +249,24 @@
       <sect2>
        <title>+null-cstring-pointer+</title>
        <para>
-         A constant returning a &null; character pointer;
+         A constant &null; character pointer.
        </para>
       </sect2>
     </sect1>
 
     <sect1>
       <title>Strings</title>
+      <sect2>
+       <title>Overview</title>
+       <para>
+         &uffi; has functions to two types of <varname>C</varname>-compatible 
+         strings, <emphasis>cstring</emphasis> and <emphasis>foreign</emphasis> strings.
+cstrings are used as parameters to and from functions. An implementation, such as CMUCL,
+may not convert these to a foreign type for efficiency sake. Thus, it is not
+possible to "allocate" a cstring. In contrast, foreign strings
+always need to have memory for them.
+       </para>
+      </sect2>
       <sect2>
        <title>convert-from-cstring</title>
        <para>
@@ -230,7 +323,7 @@
       <sect2>
        <title>def-function</title>
        <para>
-         This macro generates a &c; routine definition.
+         This macro generates a &c; function definition.
        </para>
       </sect2>
     </sect1>