From 735500e3a63ea34743f1b154c5556748170b9227 Mon Sep 17 00:00:00 2001
From: Matthias Benkard <code@mail.matthias.benkard.de>
Date: Wed, 5 Mar 2008 16:12:05 +0100
Subject: Document FOREIGN-VALUE, FOREIGN-STRUCT, and FOREIGN-UNION.

darcs-hash:fb4f97a5b508a7d112fbe2b7397221389bdfd8f5
---
 Lisp/data-types.lisp | 62 +++++++++++++++++++++++++++++++++++++++++++++++-----
 1 file changed, 57 insertions(+), 5 deletions(-)

(limited to 'Lisp/data-types.lisp')

diff --git a/Lisp/data-types.lisp b/Lisp/data-types.lisp
index ad464c7..8cff29a 100644
--- a/Lisp/data-types.lisp
+++ b/Lisp/data-types.lisp
@@ -247,16 +247,68 @@ an __exception__, you can simply send it the `self' message.
      ((lisp-managed-cell :type (array boolean ())
                          :accessor foreign-value-lisp-managed-cell-p
                          :initarg :lisp-managed-cell
-                         :documentation "Whether we need to handle deallocation.")))
+                         :documentation "Whether we need to handle deallocation."))
+  (:documentation "A wrapper type for complex foreign values.
+
+## Description:
+
+Whenever a value of a `struct` or `union` type is returned by a method
+call or given as an argument to a method implemented in Lisp, it is
+encapsulated in a __foreign-value__ that by default deallocates the
+value upon its finalisation by the garbage collector.
+
+You can extract a system area pointer that points directly to the
+wrapped foreign data by calling __foreign-value-pointer__.
+
+You can control finalisation behaviour by using the
+__foreign-value-lisp-managed-p__ accessor.
+
+
+## See also:
+
+  __foreign-value-pointer__, __foreign-value-lisp-managed-p__,
+__foreign-struct__, __foreign-union__"))
 
 
-;; FIXME: Document.
 (defclass foreign-struct (foreign-value)
      ((name :type (or null string)
             :accessor foreign-struct-name
-            :initarg :name)))
+            :initarg :name))
+  (:documentation "A wrapper type for foreign struct values.
+
+## Description:
+
+Foreign values of type `struct` are encapsulated in **object**s of
+**type** __foreign-struct__ when returned by a method call or otherwise
+acquired by Lisp code through the Objective-C bridge.
+
+For details on how to access the wrapped data and control finalisation
+behaviour, see the entry about the type __foreign-value__.
+
+
+## See also:
+
+  __foreign-value-pointer__, __foreign-value-lisp-managed-p__,
+__foreign-value__, __foreign-union__"))
+
+
+(defclass foreign-union (foreign-struct) ()
+  (:documentation "A wrapper type for foreign union values.
+
+## Description:
+
+Foreign values of type `union` are encapsulated in **object**s of
+**type** __foreign-union__ when returned by a method call or otherwise
+acquired by Lisp code through the Objective-C bridge.
+
+For details on how to access the wrapped data and control finalisation
+behaviour, see the entry about the type __foreign-value__.
+
+
+## See also:
 
-(defclass foreign-union (foreign-struct) ())
+  __foreign-value-pointer__, __foreign-value-lisp-managed-p__,
+__foreign-value__, __foreign-struct__"))
 
 
 ;; The following are for private use only.
@@ -319,7 +371,7 @@ _foreign-value-lisp-managed-p_ returns: a **boolean**.
 
 When a value of a `struct` or `union` type is returned by a method call
 or given as an argument to a method implemented in Lisp, it is
-encapsulated in a __foreign-struct__ that by default deallocates the
+encapsulated in a __foreign-value__ that by default deallocates the
 value upon its finalisation by the garbage collector.
 
 _foreign-value-lisp-managed-p_ determines whether this automatic
-- 
cgit v1.2.3