Improve documentation.

darcs-hash:2d562d82a7d51808058ac9c42bd54008486ec646

2 files changed, 68 insertions, 55 deletions

diff --git a/Lisp/libobjcl.lisp b/Lisp/libobjcl.lisp
index 296a670..21d0113 100644
--- a/Lisp/libobjcl.lisp
+++ b/Lisp/libobjcl.lisp
@@ -63,43 +63,48 @@
 (defun find-objc-class (class-name)
   "Retrieve an Objective C class by name.
 
-CLASS-NAME: a symbol or a string.
+## Arguments and Values:
 
-Returns: an OBJC-CLASS object representing the class whose name is
-CLASS-NAME.
+*class-name* --- a **symbol** or a **string**.
 
+Returns: *class* --- an __objc-class__ object representing the Objective
+C class whose name is *class-name*.
 
-If CLASS-NAME is a symbol which does not contain a hyphen, its symbol
-name is converted to lower case except for the first letter, which is
-left intact, and the resulting string used as if directly given as an
-argument to FIND-OBJC-CLASS.
 
-If CLASS-NAME is a symbol which containts a hyphen, its symbol name is
-split into components seperated by hyphens and each component is
-converted into a string according to the following rules:
+## Description:
 
- 1. The first component is fully converted to upper case except for its
- first letter, which is left intact.
+If *class-name* is a **symbol** which does not contain a hyphen, its
+**name** is converted to **lowercase** except for the first letter,
+which is left intact, and the resulting **string** used as if directly
+given as an **argument** to __find-objc-class__.
 
- 2. Any additional components have all of their letters converted to
- lower case, except for their first letters, which are left intact.
+If *class-name* is a **symbol** which containts a hyphen, its **name**
+is split into components separated by hyphens and each component
+converted into a **string** according to the following rules:
+
+1. The first component is fully converted to **uppercase** except for
+   its first letter, which is left intact.
+
+2. Any additional components have all of their letters converted to
+   **lowercase**, except for their first letters, which are left intact.
 
 After that, the components are concatenated in order and the resulting
-string used as if directly given as an argument to FIND-OBJC-CLASS.
+**string** used as if directly given as an **argument** to
+__find-objc-class__.
 
 
-Examples:
+## Examples:
 
-    (find-objc-class \"NSObject\")   ;=> #<OBJC-CLASS NSObject>
+    (find-objc-class \"NSObject\")     ;=> #<OBJC-CLASS NSObject>
     (find-objc-class 'ns-object)     ;=> #<OBJC-CLASS NSObject>
     (find-objc-class 'nsobject)      ;=> NIL
 
 
-Rationale:
+## Rationale:
 
 The first component of an Objective C class name is conventionally
 thought of as a namespace identifier.  It is therefore sensible to
-expect it to be converted to upper case by default, which is the
+expect it to be converted to **uppercase** by default, which is the
 conventional case for namespace identifiers in Objective C."
 
   (typecase class-name
diff --git a/Lisp/method-invocation.lisp b/Lisp/method-invocation.lisp
index 8de77dd..6461743 100644
--- a/Lisp/method-invocation.lisp
+++ b/Lisp/method-invocation.lisp
@@ -5,36 +5,40 @@
 (defun invoke (receiver message-start &rest message-components)
   "Send a message to an Objective C instance.
 
+## Arguments and Values:
+
 *receiver* --- an Objective C wrapper object.
 
-*message-start* --- a symbol.
+*message-start* --- a **symbol**.
 
-*message-components* --- an alternating list of arguments and message
-name component symbols.
+*message-components* --- an alternating **list** of **object**s and
+**symbol**s.
 
 Returns: *result* --- the return value of the method invocation.
 
 
-Each message name component is first split into parts seperated by
-hyphens and each part is converted into a string according to the
-following rules:
+## Description:
 
-1. The first part is fully converted to lower case.
+All even-numbered *message components* are collected in order and the
+resulting **list** used as if as additional **argument**s to
+__invoke-by-name__.
 
-2. Any additional parts are also fully converted to lower case except
-   for their first letters, which are left intact.
+All uneven-numbered *message components*, which must be **symbol**s, are
+first split into parts separated by hyphens and each part converted into
+a **string** according to the following rules:
 
-3. If the symbol is a keyword symbol, the resulting string is suffixed
-   by a colon (`:').
+1. The first part is fully converted to **lowercase**.
+
+2. Any additional parts are also fully converted to **lowercase** except
+   for their first letters, which are left intact.
 
-After that, all parts are concatenated in order to form a single message
-component.  The message components are in turn concatenated in order to
-form the message name which is used as if the second argument to a call
-to _invoke-by-name_.
+3. If the symbol is a **keyword**, the resulting **string** is suffixed
+   by a **colon** (`:').
 
-The message components that are not message name components are
-collected in order and the resulting list used as if as additional
-arguments to _invoke-by-name_.
+After that, all parts are concatenated in order to form a
+single *message name component*.  The *message name components* are in
+turn concatenated in order to form the *message name* which is used as
+if as the second **argument** to __invoke-by-name__.
 
 
 ## Examples:
@@ -59,7 +63,7 @@ arguments to _invoke-by-name_.
 
 ## See also:
 
-INVOKE-BY-NAME"
+  __invoke-by-name__"
 
   (flet ((message-component->string (symbol)
            (let* ((components (split-sequence #\- (symbol-name symbol)
@@ -95,33 +99,37 @@ INVOKE-BY-NAME"
 (defun invoke-by-name (receiver method-name &rest args)
   "Send a message to an Objective C object by the name of the method.
 
-RECEIVER: an Objective C wrapper object.
+## Arguments and Values:
 
-METHOD-NAME: a string.
+*receiver* --- an Objective C wrapper object.
 
-ARGS: a list of objects.
+*method-name* --- a **string**.
 
-Returns: the return value of the method invocation.
+*args* --- a list of **object**s.
 
+Returns: *result* --- the return value of the method invocation.
 
-Examples:
 
- (invoke-by-name (find-objc-class 'ns-string)
-                 \"stringWithCString:\" \"Mulk.\")
-   ;=> #<GSCBufferString `Mulk.' {5B36087}>
+## Examples:
 
- (invoke-by-name (find-objc-class 'ns-object)
-                 \"self\")
-   ;=> #<NSObject `NSObject' {16ECF598}>
+    (invoke-by-name (find-objc-class 'ns-string)
+                    \"stringWithCString:\" \"Mulk.\")
+      ;=> #<GSCBufferString `Mulk.' {5B36087}>
+
+    (invoke-by-name (find-objc-class 'ns-object)
+                    \"self\")
+      ;=> #<NSObject `NSObject' {16ECF598}>
+
+    (invoke-by-name (find-objc-class 'ns-string)
+                    \"stringWithCString:encoding:\"
+                    \"Mulk.\"
+                    4)
+      ;=> #<GSCBufferString `Mulk.' {5B36087}>
 
- (invoke-by-name (find-objc-class 'ns-string)
-                 \"stringWithCString:encoding:\"
-                 \"Mulk.\"
-                 4)
-   ;=> #<GSCBufferString `Mulk.' {5B36087}>
 
+## See also:
 
-See also: INVOKE"
+  __invoke__"
 
   (let* ((arglist (arglist-intersperse-types
                    (mapcar #'lisp->obj-data args)))