Properly document INVOKE and INVOKE-BY-NAME.

darcs-hash:f0d069d3c295135cad49752aeb05f96cefd9a753

1 files changed, 86 insertions, 2 deletions

diff --git a/Lisp/method-invocation.lisp b/Lisp/method-invocation.lisp
index c7e8810..252426f 100644
--- a/Lisp/method-invocation.lisp
+++ b/Lisp/method-invocation.lisp
@@ -3,7 +3,62 @@
 
 ;;; (@* "Method invocation")
 (defun invoke (receiver message-start &rest message-components)
-  "FIXME"
+  "Send a message to an Objective C instance.
+
+RECEIVER: an Objective C wrapper object.
+
+MESSAGE-START: a symbol.
+
+MESSAGE-COMPONENTS: an alternating list of arguments and message name
+component symbols.
+
+Returns: 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:
+
+ 1. The first part is fully converted to lower case.
+
+ 2. Any additional parts are also fully converted to lower case except
+ for their first letters, which are left intact.
+
+ 3. If the symbol is a keyword symbol, the resulting string is suffixed
+ by a colon (`:').
+
+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.
+
+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.
+
+
+Examples:
+
+ (invoke (find-objc-class 'ns-string)
+         :string-with-c-string \"Mulk.\")
+   ;=> #<GSCBufferString `Mulk.' {5B36087}>
+
+ (invoke (find-objc-class 'ns-object)
+         'self)                           
+   ;=> #<NSObject `NSObject' {16ECF598}>
+
+ (invoke (find-objc-class 'ns-object)
+         'name)                           
+   ;=> \"NSObject\"
+
+ (invoke (find-objc-class 'ns-string)
+         :string-with-c-string \"Mulk.\"
+         :encoding 4)
+   ;=> #<GSCBufferString `Mulk.' {5B36087}>
+
+
+See also: INVOKE-BY-NAME"
+
   (flet ((message-component->string (symbol)
            (let* ((components (split-sequence #\- (symbol-name symbol)
                                               :remove-empty-subseqs t))
@@ -36,7 +91,36 @@
 
 
 (defun invoke-by-name (receiver method-name &rest args)
-  "FIXME"
+  "Send a message to an Objective C object by the name of the method.
+
+RECEIVER: an Objective C wrapper object.
+
+METHOD-NAME: a string.
+
+ARGS: a list of objects.
+
+Returns: the return value of the method invocation.
+
+
+Examples:
+
+ (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}>
+
+
+See also: INVOKE"
+
   (let* ((arglist (arglist-intersperse-types
                    (mapcar #'lisp->obj-data args)))
          (return-value (apply-macro '%objcl-invoke-class-method