summaryrefslogtreecommitdiff
diff options
context:
space:
mode:
authorMatthias Benkard <code@mail.matthias.benkard.de>2008-03-05 16:12:05 +0100
committerMatthias Benkard <code@mail.matthias.benkard.de>2008-03-05 16:12:05 +0100
commit735500e3a63ea34743f1b154c5556748170b9227 (patch)
tree5c8f892be04223db48ac737cb897a23665e935ae
parent02d4f57b64333e94a4051e5299be20e0a600cfd1 (diff)
Document FOREIGN-VALUE, FOREIGN-STRUCT, and FOREIGN-UNION.
darcs-hash:fb4f97a5b508a7d112fbe2b7397221389bdfd8f5
-rw-r--r--Lisp/data-types.lisp62
1 files changed, 57 insertions, 5 deletions
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