From: Kevin M. Rosenberg <kevin@rosenberg.net>
Date: Sun, 10 Mar 2002 12:00:07 +0000 (+0000)
Subject: r1534: *** empty log message ***
X-Git-Tag: v1.6.1~614
X-Git-Url: http://git.kpe.io/?a=commitdiff_plain;h=737a3e3a8d18dd80f4cda0d93bc20a3b5677dbee;hp=ce76fe27cbbb4f6bac18a0ffd7bd4f454f7d4a02;p=uffi.git

r1534: *** empty log message ***
---

diff --git a/ChangeLog b/ChangeLog
index 6ed9d59..ab61ff2 100644
--- 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 a42cc8d..d432b9f 100644
--- 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 5eb4f9e..0bc5b47 100644
--- 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>