Update documentation.

darcs-hash:af9cfdb8adda53a3459722f8156c54a3d31bfaf1

2 files changed, 35 insertions, 2 deletions

diff --git a/Lisp/data-types.lisp b/Lisp/data-types.lisp
index bd2fae4..a5ec1ba 100644
--- a/Lisp/data-types.lisp
+++ b/Lisp/data-types.lisp
@@ -54,12 +54,30 @@
 ## Description:
 
 Method selectors are Objective-C's equivalent to what Common Lisp calls
-**symbols**.  Their use is restricted to retrieving methods by name.
+**symbols**.  Their use, however, is restricted to retrieving methods by
+name.
+
+In Common Lisp, you can **funcall** a __selector__ directly (see the
+note below for details and why you may want to do this).
 
 __selector__ objects cannot be created by means of __make-instance__.
 Use __find-selector__ instead.
 
 
+## Note:
+
+Instead of using __invoke__, which is neither macro-friendly nor very
+useful for method selection at run-time, you may **funcall** selectors
+directly.  Naturally, __apply__ works as well.
+
+The following calls are all equivalent:
+
+    (invoke-by-name instance \"stringWithCString:encoding:\" \"Mulk.\" 4)
+    (invoke instance :string-with-c-string \"Mulk.\" :encoding 4)
+    (funcall (selector \"stringWithCString:encoding:\") instance \"Mulk.\" 4)
+    (apply (selector \"stringWithCString:encoding:\") (list instance \"Mulk.\" 4))
+
+
 ## See also:
 
   __find-selector__"))
@@ -77,7 +95,7 @@ Use __find-selector__ instead.
        (apply #'invoke-by-name receiver selector args))))
 
 
-(defclass id         (c-pointer-wrapper) ()
+(defclass id (c-pointer-wrapper) ()
   (:documentation "An instance of an Objective-C class.
 
 ## Description:
diff --git a/Lisp/method-invocation.lisp b/Lisp/method-invocation.lisp
index c0bad01..9aae94d 100644
--- a/Lisp/method-invocation.lisp
+++ b/Lisp/method-invocation.lisp
@@ -108,6 +108,20 @@ separating parts by hyphens works nicely in all of the `:INVERT`,
 *modern mode*.
 
 
+## Note 2:
+
+Instead of using __invoke__, which is neither macro-friendly nor very
+useful for method selection at run-time, you may **funcall** selectors
+directly.  Naturally, __apply__ works as well.
+
+The following calls are all equivalent:
+
+    (invoke-by-name instance \"stringWithCString:encoding:\" \"Mulk.\" 4)
+    (invoke instance :string-with-c-string \"Mulk.\" :encoding 4)
+    (funcall (selector \"stringWithCString:encoding:\") instance \"Mulk.\" 4)
+    (apply (selector \"stringWithCString:encoding:\") (list instance \"Mulk.\" 4))
+
+
 ## See also:
 
   __invoke-by-name__"
@@ -168,6 +182,7 @@ are all equivalent:
 In fact, using __invoke-by-name__ is discouraged in favour of the latter
 form.
 
+
 ## Rationale:
 
 Whereas __invoke__ tries to make writing as well as reading method