added explanatory comments

[SVN r7979]

extclass.cpp

@@ -218,6 +218,27 @@ ExtensionClassBase::ExtensionClassBase(const char* name)
 {
 }
 
+/*
+    This function is used in from_python() to convert wrapped classes that are 
+    related by inheritance. The problem is this: although C++ provides all necessary 
+    conversion operators, source and target of a conversion must be known at compile
+    time. However, in Python we want to convert classes at runtime. The solution is to
+    generate conversion functions at compile time, register them within the appropriate 
+    class objects and call them when a particular runtime conversion is required.
+    
+    If functions for any possible conversion have to be stored, their number will grow 
+    qudratically. To reduce this number, we actually store only conversion functions
+    between adjacent levels in the inheritance tree. By traversing the tree recursively,
+    we can build any allowed conversion as a concatenation of simple conversions. This
+    traversal is done in the functions try_base_class_conversions() and 
+    try_derived_class_conversions(). If a particular conversion is impossible, all
+    conversion functions will return a NULL pointer.
+    
+    The function extract_from_holder() attempts to actually extract the pointer to
+    the contained object from an InstanceHolderBase (a wrapper class). A conversion
+    of the held object to 'T *' is allowed when the conversion 
+    'dynamic_cast<InstanceHolde<T> *>(an_instance_holder_base)' succeeds.
+*/
 void * ExtensionClassBase::try_class_conversions(InstanceHolderBase * object) const
 {
     void * result = try_derived_class_conversions(object);