Document INITIALISE-RUNTIME, SHUTDOWN-RUNTIME and INSTALL-READER-SYNTAX.

darcs-hash:9b2b0d2e48753404b9423a826f3617d3a87c4df8

2 files changed, 154 insertions, 1 deletions

diff --git a/Lisp/libobjcl.lisp b/Lisp/libobjcl.lisp
index 82b9a8f..12a880c 100644
--- a/Lisp/libobjcl.lisp
+++ b/Lisp/libobjcl.lisp
@@ -20,9 +20,54 @@
 
 ;; FIXME: docs
 (defcfun ("objcl_initialise_runtime" initialise-runtime) :void)
+(setf (documentation #'initialise-runtime 'function)
+      "Initialise the Objective C runtime.
+
+## Description:
+
+The function __initialise-runtime__ makes all the necessary arrangements
+for object instantiation and method calls to work.  In particular, it
+creates an autorelease pool in order to make the use of Objective C's
+semiautomatic reference counting memory management possible, which is
+used internally by Objective CL.
+
+Note that, as the autorelease pool created by __initialise-runtime__ is
+currently only deallocated and its containees released when
+__shutdown-runtime__ is called, it is generally advisable to make use of
+AppKit's automatic creation and deletion auf autorelease pools, if
+possible.  Naturally, AppKit-based applications need not worry about
+this, but be aware that they do need to call __initialise-runtime__
+before making any other Objective C calls.
+
+
+## See also:
+
+  __shutdown-runtime__")
+
 
 ;; FIXME: docs
 (defcfun ("objcl_shutdown_runtime" shutdown-runtime) :void)
+(setf (documentation #'shutdown-runtime 'function)
+      "Shut the Objective C runtime down.
+
+## Description:
+
+The function __shutdown-runtime__ cleans the environment up.  In
+particular, it tries to release all the objects retained in any
+autorelease pools created by __initialise-runtime__.
+
+Note that even if you make use of AppKit, which manages its own
+autorelease pools, you must call __initialise-runtime__ before making
+any Objective C calls, and you should call __shutdown-runtime__ when you
+are finished with Objective C, since Objective CL makes use of
+autoreleased objects internally before you are even able to retrieve any
+objects or classes, let alone send messages to them.
+
+
+## See also:
+
+  __initialise-runtime__")
+
 
 (defcfun ("objcl_invoke_instance_method"
           %objcl-invoke-instance-method) obj-data
diff --git a/Lisp/reader-syntax.lisp b/Lisp/reader-syntax.lisp
index ccb4ff0..497253e 100644
--- a/Lisp/reader-syntax.lisp
+++ b/Lisp/reader-syntax.lisp
@@ -2,7 +2,115 @@
 
 
 (defun install-reader-syntax ()
-  "FIXME"
+  "Install an Objective-C-like **reader macro** for Objective C method
+ calls.
+
+## Description:
+
+The **reader macro** installed by __install-reader-syntax__ closely
+resembles the conventional method call syntax of Objective C.  In fact,
+any differences between standard Objective C method call syntax and this
+**reader macro** that are not documented here is probably a bug and
+should be reported to the maintainer.
+
+
+## Reader Macro:
+
+[\\{*receiver* | *class-name*\\} *message-name-part [[argument [[message-name-arg-pair]]*\\**]]*]
+
+message-name-arg-pair ::= *message-name-part argument*
+
+
+## Reader Macro Arguments and Values:
+
+*receiver* --- an **object**.
+
+*class-name* --- a **symbol** (not evaluated).
+
+*message-name-part* --- a **symbol** (not evaluated).
+
+*argument* -- an **object**.
+
+Returns: *result* --- the result of the method invocation.
+
+
+## Reader Macro Description:
+
+First, it is determined whether to regard the first element of the
+form as an object or as a class name according to the following rules:
+
+1. If the element is no **symbol**, it is regarded as an object.
+
+2. Otherwise, if it is a **symbol** whose **name** starts with a
+**lowercase** letter, it is regarded as an object.
+
+3. Otherwise, it is regarded as a class name.
+
+Next, the method call is parsed by alternately
+reading *message name parts* and *arguments* separated by
+whitespace.  *Message name parts* are expected to consist of
+**alphanumeric** **character**s and **colon**s, while *arguments* may
+be arbitrary Lisp expressions.  If any but the first *message name part*
+does not end with a **colon**, the effects are undefined.  Likewise, the
+effects are undefined if any *message name part* contains a **colon** in
+a position other than the end.
+
+After the parsing is done, all *message name parts* are concatenated in
+order to form a single **string** that is used as if as the second
+**argument** to __invoke-by-name__, and all *arguments* are collected in
+order and the resulting **list** used as if as a **list** of additional
+arguments to __invoke-by-name__.
+
+
+## Reader Macro Examples:
+
+    [NSString stringWithCString: \"Mulk.\"]
+      ;=> #<GSCBufferString `Mulk.' {5B36087}>
+
+    [NSObject self]
+      ;=> #<NSObject `NSObject' {16ECF598}>
+
+    [NSObject name]
+      ;=> \"NSObject\"
+
+    [[[NSObject self] self] name]
+      ;=> \"NSObject\"
+
+    [NSString stringWithCString: \"Mulk.\" encoding: 4]
+      ;=> #<GSCBufferString `Mulk.' {5B36087}>
+
+
+
+## Rationale:
+
+Objective C method names tend to be relatively verbose and are
+frequently composed of many short words like \"of\" and \"by\".  As a
+result, using __invoke__ can be quite cumbersome at times and waste
+screen real estate.  One need only compare the example call
+
+    (invoke (find-objc-class 'ns-string)
+            :string-with-c-string \"Mulk.\"
+            :encoding 4)
+
+with its reader macro counterpart
+
+    [NSString stringWithCString: \"Mulk.\" encoding: 4]
+
+to be able to see an improvement in length as well as readability.
+
+In any case, it is a matter of taste whether to prefer __invoke__ or
+Objective C syntax as it is whether to prefer the standard Common Lisp
+__loop__ facility or a widespread and well-known alternative called
+\"Iterate\".  In both cases, one can argue that one of the forms
+sacrifices an elusive quality of \"lispiness\" as well as text editor
+friendliness in favor of natural-language-style readability and
+conciseness.
+
+
+## See also:
+
+  __invoke__, __invoke-by-name__"
+
   (set-macro-character #\] (get-macro-character #\)))
 
   (set-macro-character #\[ #'(lambda (stream char)