r1581: *** empty log message ***

[uffi.git] / doc / ref.sgml

diff --git a/doc/ref.sgml b/doc/ref.sgml
index 252bdc53c8894657887f6150a7155758dedb99de..2eb2e1c438ca9bae4c460e9b8b29afba26bcf5e0 100644 (file)
--- a/doc/ref.sgml
+++ b/doc/ref.sgml
@@ -88,43 +88,55 @@
        </para>
        <itemizedlist>
          <listitem>
-           <para><constant>:char</constant> - Signed 8-bits</para>
+           <para><constant>:char</constant> - Signed 8-bits. A
+dereferenced :char pointer returns an character.</para>
+</para>
          </listitem>
          <listitem>
-           <para><constant>:unsigned-char</constant> - Unsigned 8-bits</para>
+           <para><constant>:unsigned-char</constant> - Unsigned 8-bits. A dereferenced :unsigned-char
+pointer returns an character.</para>
          </listitem>
          <listitem>
-           <para><constant>:short</constant> - Signed 16-bits</para>
+         <listitem>
+           <para><constant>:byte</constant> - Unsigned 8-bits. A
+dereferenced :byte pointer returns an integer.</para>
+         </listitem>
+         <listitem>
+           <para><constant>:short</constant> - Signed 16-bits.</para>
          </listitem>
          <listitem>
-           <para><constant>:unsigned-short</constant> - Unsigned 16-bits</para>
+           <para><constant>:unsigned-short</constant> - Unsigned 16-bits.</para>
          </listitem>
          <listitem>
-           <para><constant>:int</constant> - Signed 32-bits</para>
+           <para><constant>:int</constant> - Signed 32-bits.</para>
          </listitem>
          <listitem>
-           <para><constant>:unsigned-int</constant> - Unsigned 32-bits</para>
+           <para><constant>:unsigned-int</constant> - Unsigned 32-bits.</para>
          </listitem>
          <listitem>
-           <para><constant>:long</constant> - Signed 32-bits</para>
+           <para><constant>:long</constant> - Signed 32-bits.</para>
          </listitem>
          <listitem>
-           <para><constant>:unsigned-long</constant> - Unsigned 32-bits</para>
+           <para><constant>:unsigned-long</constant> - Unsigned 32-bits.</para>
          </listitem>
          <listitem>
-           <para><constant>:float</constant> - 32-bit floating point</para>
+           <para><constant>:float</constant> - 32-bit floating point.</para>
          </listitem>
          <listitem>
-           <para><constant>:double</constant> - 64-bit floating point</para>
+           <para><constant>:double</constant> - 64-bit floating point.</para>
          </listitem>
          <listitem>
            <para><constant>:cstring</constant> - 
-A null-terminated string used for passing and returning with a function.
+A &null; terminated string used for passing and returning characters strings with a &c; function.
            </para>
          </listitem>
          <listitem>
            <para><constant>:void</constant> - 
-The absence of a value. Used in generic pointers and in return types from functions.</para>
+The absence of a value. Used to indicate that a function does not return a value.</para>
+         </listitem>
+         <listitem>
+           <para><constant>:pointer-void</constant> - 
+Points to a generic object.</para>
          </listitem>
          <listitem>
            <para><constant>*</constant> - Used to declare a pointer to an object</para>
@@ -240,7 +252,7 @@ foreign type.
       <refsect1>
        <title>Examples</title>
        <programlisting>
-(def-foreign-type my-generic-pointer (* :void))
+(def-foreign-type my-generic-pointer :pointer-void)
 (def-foreign-type a-double-float :double-float)
 (def-foreign-type char-ptr (* :char))
        </programlisting>
@@ -327,86 +339,20 @@ abstracts the difference in implementations where some return a
        <para>None.</para>
       </refsect1>
     </refentry>
+  </reference>
 
-    <refentry id="ensure-char">
-      <refnamediv>
-       <refname>ensure-char</refname>
-       <refpurpose>Ensures value is a character.
-       </refpurpose>
-       <refclass>Macro</refclass>
-      </refnamediv>
-      <refsynopsisdiv>
-       <title>Syntax</title>
-       <synopsis>
-         <function>ensure-char</function> <replaceable>obj</replaceable> => <returnvalue>char</returnvalue>
-       </synopsis>
-      </refsynopsisdiv>
-      <refsect1>
-       <title>Arguments and Values</title>
-       <variablelist>
-         <varlistentry>
-           <term><parameter>obj</parameter></term>
-           <listitem>
-             <para>A character or integer.
-             </para>
-           </listitem>
-         </varlistentry>
-         <varlistentry>
-           <term><parameter>char</parameter></term>
-           <listitem>
-             <para>A character value.
-             </para>
-           </listitem>
-         </varlistentry>
-       </variablelist>
-      </refsect1>
-      <refsect1>
-       <title>Description</title>
-       <para>
-         Enscapsulates the fact that some implementations return a character
-and others return an integer when dereferencing a character pointer.
-       </para>
-      </refsect1>
-      <refsect1>
-       <title>Examples</title>
-       <para>
-<programlisting>
-(let ((fs (convert-to-foreign-string "a")))
-  (prog1 
-    (ensure-char (deref-pointer fs :char))
-    (free-foreign-object fs)))
-=> #\a
-</programlisting>
-       </para>
-      </refsect1>
-      <refsect1>
-       <title>Side Effects</title>
-       <para>None.</para>
-      </refsect1>
-      <refsect1>
-       <title>Affected by</title>
-       <para>None.</para>
-      </refsect1>
-      <refsect1>
-       <title>Exceptional Situations</title>
-       <para>Signals an error if <parameter>obj</parameter> is not
-an integer or character.</para>
-      </refsect1>
-    </refentry>
-</reference>
-
-<reference>
-      <title>Aggregate Types</title>
+  <reference>
+    <title>Aggregate Types</title>
     <partintro>
       <title>Overview</title>
       <para>
        Aggregate types are comprised of one or more primitive types.
       </para>
-</partintro>
+    </partintro>
 
-      <refentry id="def-enum">
-       <refnamediv>
-         <refname>def-enum</refname>
+    <refentry id="def-enum">
+      <refnamediv>
+       <refname>def-enum</refname>
        <refpurpose>Defines a &c; enumeration.
        </refpurpose>
        <refclass>Macro</refclass>
@@ -1599,7 +1545,7 @@ Can translated ASCII and binary strings.
          <varlistentry>
            <term><parameter>unsigned</parameter></term>
            <listitem>
-             <para>A boolean flag with a default value of &nil;. When true,
+             <para>A boolean flag with a default value of &t;. When true,
 marks the pointer as an <constant>:unsigned-char</constant>.
              </para>
            </listitem>
@@ -1665,7 +1611,7 @@ marks the pointer as an <constant>:unsigned-char</constant>.
          <varlistentry>
            <term><parameter>args</parameter></term>
            <listitem>
-             <para>A list of argument declarations. Use &nil; to specify no arguments.
+             <para>A list of argument declarations. If &nil;, indicates that the function does not take any arguments.
              </para>
            </listitem>
          </varlistentry>
@@ -1679,7 +1625,7 @@ marks the pointer as an <constant>:unsigned-char</constant>.
            <term><returnvalue>returning</returnvalue></term>
            <listitem>
              <para>A declaration specifying the result type of the
-foreign function.
+foreign function. If <constant>:void</constant> indicates module does not return any value.
              </para>
            </listitem>
          </varlistentry>