Document and export classes and special variables.

darcs-hash:8ad27577c51deee5dbfb55b3520d91297cb97cb1

3 files changed, 170 insertions, 8 deletions

diff --git a/Lisp/data-types.lisp b/Lisp/data-types.lisp
index 16d9147..606c0c4 100644
--- a/Lisp/data-types.lisp
+++ b/Lisp/data-types.lisp
@@ -45,16 +45,65 @@
             :initform nil)))
 
 
-(defclass selector   (c-pointer-wrapper) ())
-(defclass id         (c-pointer-wrapper) ())
-(defclass objc-class (c-pointer-wrapper) ())
+(defclass selector   (c-pointer-wrapper) ()
+  (:documentation "An Objective C method selector.
+
+## Description:
+
+Method selectors are Objective C's equivalent to what Common Lisp calls
+**symbols**.  Their use is restricted to retrieving methods by name.
+
+__selector__ objects cannot be created by means of __make-instance__.
+Use __find-selector__ instead.
+
+
+## See also:
+
+  __find-selector__"))
+
+
+(defclass id         (c-pointer-wrapper) ()
+  (:documentation "An instance of an Objective C class.
+
+## Description:
+
+The class __id__ serves as a general-purpose container for all kinds of
+Objective C objects that are instances of some Objective C class, that
+is, neither primitive C values nor __selector__, __class__ or
+__exception__ objects.
+
+__id__ objects cannot be created by means of __make-instance__.  Use
+a suitable class method instead as you would in Objective C.
+
+
+## Examples:
+
+    (invoke (find-objc-class 'ns-object)
+            'self)
+      ;=> #<NSObject `NSObject' {16ECF598}>
+
+    (invoke (find-objc-class 'ns-string)
+            :string-with-c-string \"Mulk.\")
+      ;=> #<GSCBufferString `Mulk.' {5B36087}>
+
+    (invoke (find-objc-class 'ns-string)
+            'new)
+      ;=> #<GSCBufferString `' {FFFFFFE}>
+
+
+## See also:
+
+  __invoke__, __invoke-by-name__, __exception__"))
+
+
+(defclass objc-class (c-pointer-wrapper) ()
+  (:documentation ""))
 
 
 (define-condition exception (error)
   ((pointer :type     c-pointer
             :accessor pointer-to
             :initarg  :pointer))
-  (:documentation "The condition type for Objective C exceptions.")
   (:report (lambda (condition stream)
              (format stream
                      "The Objective C runtime has issued an exception of ~
@@ -65,7 +114,44 @@
                       "UTF8String")
                      (invoke-by-name
                       (invoke-by-name condition "reason")
-                      "UTF8String")))))
+                      "UTF8String"))))
+  (:documentation "The condition type for Objective C exceptions.
+
+## Description:
+
+Whenever an Objective C call made by means of __invoke__ or
+__invoke-by-name__ raises an exception, the exception is propagated to
+the Lisp side by being encapsulated in an __exception__ object and
+signaled.
+
+Note that it is currently impossible to directly extract the original
+Objective C exception from an __exception__ object, although it might
+arguably be desirable to do so.  As __exception__ objects behave just
+like __id__ objects in almost all circumstances, this is not much of a
+problem, though.  If you really do need an __id__ instance rather than
+an __exception__, you can simply send it the `self' message.
+
+
+## Examples:
+
+\(With __install-reader-syntax__ enabled.)
+
+    (handler-case
+        [NSArray selph]   ; oops, typo
+      (exception (e)
+        e))
+      ;=> #<MULK.OBJECTIVE-CL:EXCEPTION NSInvalidArgumentException {1048D63}>
+
+    (class-of *)
+      ;=> #<CONDITION-CLASS EXCEPTION>
+
+    (class-of [** self])
+      ;=> #<STANDARD-CLASS ID>
+
+
+## See also:
+
+  __id__"))
 
 
 (defgeneric objcl-eql (obj1 obj2))
diff --git a/Lisp/defpackage.lisp b/Lisp/defpackage.lisp
index af51e52..c3fcc2e 100644
--- a/Lisp/defpackage.lisp
+++ b/Lisp/defpackage.lisp
@@ -1,6 +1,8 @@
 (defpackage #:mulk.objective-cl
-  (:nicknames #:objcl)
+  (:nicknames #:objcl #:objective-cl #:mulk.objcl)
   (:use #:cl #:cffi #:split-sequence)
+
+           ;; Functions
   (:export #:initialise-runtime
            #:shutdown-runtime
            #:install-reader-syntax
@@ -8,4 +10,14 @@
            #:invoke
            #:find-objc-class
            #:find-selector
-           #:*trace-method-calls*))
+
+           ;; Special variables
+           #:*trace-method-calls*
+
+           ;; Classes
+           #:id
+           #:selector
+           #:exception
+
+           ;; Metaclasses
+           #:objective-c-class))
diff --git a/Lisp/parameters.lisp b/Lisp/parameters.lisp
index 3974b89..e9e3057 100644
--- a/Lisp/parameters.lisp
+++ b/Lisp/parameters.lisp
@@ -5,4 +5,68 @@
 (defvar *skip-retaining*     nil)
 
 (defvar *trace-method-calls* nil
-  "FIXME")
+  "Whether to print trace messages of all Objective C method calls.
+
+## Value Type:
+
+a **generalized boolean**.
+
+
+## Initial Value:
+
+__nil__.
+
+
+## Description:
+
+Sometimes it is useful to find out exactly which message calls are done
+in a piece of code that is executed.  If __*trace-method-calls*__ is
+**true**, Objective CL tries to print trace messages to
+__*terminal-io*__ that can be useful for understanding the behaviour
+both of application code and the internals of Objective CL itself.
+
+If __*trace-method-calls*__ is __nil__ (which is the default), no trace
+messages are printed.
+
+Note that there is currently no way of determining the receivers of
+messages.  As this limitation severely limits the usefulness of the
+trace messages, it is expected to be lifted in a future version of
+Objective CL.
+
+
+## Examples:
+
+\(With __install-reader-syntax__ enabled.)
+
+    (defvar *tmp*)
+    (setq *trace-method-calls* t)
+
+    (setq *tmp* [NSString new])
+    ; Invoking [new].
+
+    (setq *tmp* [NSString string])
+    ; Invoking [string].
+    ; Invoking [retain].
+
+    (setq *tmp* nil)
+    (gc :full t)
+    ; Invoking [release].
+    ; Invoking [release].
+
+    (setq *trace-method-calls* nil)
+
+\(Note that objects created by a call to `new' are not retained, because
+it is the user's (that is, the Objective CL framework's) responsibility
+to release them, while convenience constructors such as `string' return
+objects that have already had `autorelease' called on them and must thus
+be retained not to be garbage-collected prematurely.)
+
+
+## Affected By:
+
+  __*terminal-io*__
+
+
+## See also:
+
+  __invoke__, __invoke-by-name__")