summaryrefslogtreecommitdiff
path: root/Lisp
diff options
context:
space:
mode:
authorMatthias Benkard <code@mail.matthias.benkard.de>2007-08-05 16:18:12 +0200
committerMatthias Benkard <code@mail.matthias.benkard.de>2007-08-05 16:18:12 +0200
commitc185ae1549bf2f99c42ab9a239bc698e2c0957c7 (patch)
tree7a06eea31bada1682d5bfa68369b7e7fbdd4470d /Lisp
parent9197c82287d253843e8fed25ccfd17a27ed39fa3 (diff)
Improve documentation.
darcs-hash:2d562d82a7d51808058ac9c42bd54008486ec646
Diffstat (limited to 'Lisp')
-rw-r--r--Lisp/libobjcl.lisp43
-rw-r--r--Lisp/method-invocation.lisp80
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)))