Document COLLECT-CLASSES and COLLECT-METHODS.

darcs-hash:5f9f283cf4206188d49b9a7ac61f247e65ef72c5

2 files changed, 60 insertions, 0 deletions

diff --git a/Lisp/class-definition.lisp b/Lisp/class-definition.lisp
index d6cc6a9..8c8672d 100644
--- a/Lisp/class-definition.lisp
+++ b/Lisp/class-definition.lisp
@@ -507,4 +507,39 @@ __define-objective-c-method__"
 
 
 (defun collect-classes ()
+  "Intern all __objective-c-class__es known to the runtime.
+
+## Description:
+
+__collect-classes__ makes all Objective-C classes known to the
+Objective-C runtime available as __class__ metaobjects in the
+_objective-c-classes_ **package** (that is, the _ns_ namespace).
+
+Calling _collect-classes_ is optional.  It allows you to use
+__find-class__ instead of __find-objc-class__, but this is purely an
+aesthetic improvement.  _collect-classes_ is not necessary to use
+Objective-CL productively.
+
+
+## Note:
+
+_collect-classes_ may take a very long time to complete depending on the
+Lisp implementation.  Some implementations are not optimised to create
+such a large number of classes along with their metaclasses on the fly.
+If you care about portability, you may therefore want to do without the
+extra convenience that _collect-classes_ offers.
+
+
+## Note 2:
+
+Even though when subclassing a foreign __class__, it needs to be
+available as a __class__ metaobject in the _objective-c-classes_
+package, you need not call _collect-classes_ before subclassing a
+foreign __class__, because __define-objective-c-class__ takes care to
+intern any missing superclass objects.
+
+
+## See also:
+
+  __collect-methods__"
   (%objcl-for-each-class-do (callback collect-class)))
diff --git a/Lisp/libobjcl.lisp b/Lisp/libobjcl.lisp
index 92f5547..f733211 100644
--- a/Lisp/libobjcl.lisp
+++ b/Lisp/libobjcl.lisp
@@ -943,6 +943,31 @@ separating parts by hyphens works nicely in all of the `:INVERT`,
     (collect-methods (%objcl-class-metaclass class))))
 
 (defun collect-methods ()
+  "Intern all method __selector__s known to the runtime.
+
+## Description:
+
+For the syntax enhancement provided by __enable-method-syntax__ to work,
+all method __selector__s must be available as the __fdefinition__ of the
+**symbol** whose __symbol-name__ is the __selector__'s name and which
+are **accessible** in the package _objective-cl-selectors_.
+__collect-methods__ ensures that all __selector__s that are known to the
+Objective-C runtime as the names of methods of any classes are
+registered in this way.
+
+Normally, __collect-methods__ need not be called by user code, as it is
+called once at system load-time as well as whenever a framework is
+loaded by Objective-CL, but if the user dynamically loads any libraries
+or frameworks by calling FFI routines (like, for instance,
+_cffi:load-foreign-library_) directly, __collect-methods__ must be
+called if the newly introduced __selector__s are to be available to Lisp
+code written using the syntax enhancement provided by
+__enable-method-syntax__.
+
+
+## See also:
+
+  __collect-classes__"
   (%objcl-for-each-class-do (callback collect-class-methods)))