[pygccxml-commit] SF.net SVN: pygccxml: [996] pyplusplus_dev/pyplusplus/decl_wrappers

[<rom...@us...>]

Revision: 996
          http://svn.sourceforge.net/pygccxml/?rev=996&view=rev
Author:   roman_yakovenko
Date:     2007-04-17 05:40:13 -0700 (Tue, 17 Apr 2007)

Log Message:
-----------
small docs improvements 

Modified Paths:
--------------
    pyplusplus_dev/pyplusplus/decl_wrappers/__init__.py
    pyplusplus_dev/pyplusplus/decl_wrappers/call_policies.py
    pyplusplus_dev/pyplusplus/decl_wrappers/calldef_wrapper.py

Modified: pyplusplus_dev/pyplusplus/decl_wrappers/__init__.py
===================================================================
--- pyplusplus_dev/pyplusplus/decl_wrappers/__init__.py	2007-04-17 07:28:51 UTC (rev 995)
+++ pyplusplus_dev/pyplusplus/decl_wrappers/__init__.py	2007-04-17 12:40:13 UTC (rev 996)
@@ -3,34 +3,11 @@
 # accompanying file LICENSE_1_0.txt or copy at
 # http://www.boost.org/LICENSE_1_0.txt)
 
-"""Declaration decorators.
+"""Code generator configuration classes
 
-This sub-package contains the Py++ specific declaration objects
-that are the nodes of the declaration tree. In addition to the
-interface of the declarations in the pygccxml package the objects in
-this package also provide a I{decoration} interface. This interface
-allows customizing the bindings and influences the code creators that
-have to be generated in subsequent steps.
-
-Each node is derived from its corresponding node in the pygccxml
-package and from a decorator base class.
-
-You may encounter the following objects in a declaration tree:
-
-  - L{namespace_t}
-  - L{typedef_t}
-  - L{variable_t}
-  - L{enumeration_t}
-  - L{casting_operator_t}
-  - L{free_function_t}
-  - L{free_operator_t}
-  - L{class_declaration_t}
-  - L{class_t}
-  - L{constructor_t}
-  - L{destructor_t}
-  - L{member_function_t}
-  - L{member_operator_t}
-
+L{pygccxml.declarations} package contains classes, which describe C++ declarations.
+This package contains classes that derive from the L{pygccxml.declarations} classes.
+The classes in this package allow you to configure the code generator.
 """
 
 import algorithm
@@ -110,9 +87,7 @@
 import python_traits
 
 class dwfactory_t( declarations.decl_factory_t ):
-    """
-    declarations factory class
-    """
+    """declarations factory class"""
     def __init__(self):
         declarations.decl_factory_t.__init__(self)
 

Modified: pyplusplus_dev/pyplusplus/decl_wrappers/call_policies.py
===================================================================
--- pyplusplus_dev/pyplusplus/decl_wrappers/call_policies.py	2007-04-17 07:28:51 UTC (rev 995)
+++ pyplusplus_dev/pyplusplus/decl_wrappers/call_policies.py	2007-04-17 12:40:13 UTC (rev 996)
@@ -9,6 +9,7 @@
 import python_traits
 from pygccxml import declarations
 
+#keeps file name, where Py++ defined call policies will be defined
 PYPP_CALL_POLICIES_HEADER_FILE = "__call_policies.pypp.hpp"
 
 class CREATION_POLICY:
@@ -17,7 +18,7 @@
     AS_TEMPLATE_ARGUMENT = 'as template argument'
 
 class call_policy_t(object):
-    """Base class for all call polices classes"""
+    """base class for all classes, which generate "call policies" code"""
     def __init__(self):
         object.__init__(self)
 
@@ -36,18 +37,19 @@
         return code
 
     def create_type(self):
+        """return call policies class declaration as string"""
         return self.create( None, CREATION_POLICY.AS_TEMPLATE_ARGUMENT )
 
     def create_template_arg( self, function_creator ):
+        """return call policies class declaration as string"""
         return self.create( function_creator, CREATION_POLICY.AS_TEMPLATE_ARGUMENT )
 
     def is_default( self ):
-        """Returns True is self is instance of L{default_call_policies_t} class"""
-        #Small hack that allows to write nicer code
+        """return True is self is instance of L{default_call_policies_t} class"""
         return False
 
     def is_predefined( self ):
-        """Returns True if call policy is defined in Boost.Python library, False otherwise"""
+        """return True if call policy is defined in Boost.Python library, False otherwise"""
         return True
 
     def _create_impl( self, function_creator ):
@@ -55,11 +57,11 @@
 
     @property
     def header_file(self):
-        """Return name of the header file to be included"""
+        """return a name of the header file the call policy is defined in"""
         return "boost/python.hpp"
 
 class default_call_policies_t(call_policy_t):
-    """implementation for ::boost::python::default_call_policies"""
+    """implements code generation for boost::python::default_call_policies"""
     def __init__( self ):
         call_policy_t.__init__( self )
 
@@ -73,11 +75,11 @@
         return 'default_call_policies'
 
 def default_call_policies():
-    """create ::boost::python::default_call_policies"""
+    """create ::boost::python::default_call_policies call policies code generator"""
     return default_call_policies_t()
 
 class compound_policy_t( call_policy_t ):
-    """base class for all call policies, except default one"""
+    """base class for all call policies, except the default one"""
     def __init__( self, base=None ):
         call_policy_t.__init__( self )
         self._base = base
@@ -111,7 +113,7 @@
         return declarations.templates.join( name, args )
 
 class return_argument_t( compound_policy_t ):
-    """implementation for ::boost::python::return_argument call policies"""
+    """implements code generation for boost::python::return_argument call policies"""
     def __init__( self, position=1, base=None):
         compound_policy_t.__init__( self, base )
         self._position = position
@@ -135,12 +137,15 @@
             return [ str( self.position ) ]
 
 def return_arg( arg_pos, base=None ):
+    """create boost::python::return_arg call policies code generator"""
     return return_argument_t( arg_pos, base )
 
 def return_self(base=None):
+    """create boost::python::return_self call policies code generator"""
     return return_argument_t( 1, base )
 
 class return_internal_reference_t( compound_policy_t ):
+    """implements code generation for boost::python::return_internal_reference call policies"""
     def __init__( self, position=1, base=None):
         compound_policy_t.__init__( self, base )
         self._position = position
@@ -158,9 +163,11 @@
         return [ str( self.position ) ]
 
 def return_internal_reference( arg_pos=1, base=None):
+    """create boost::python::return_internal_reference call policies code generator"""
     return return_internal_reference_t( arg_pos, base )
 
 class with_custodian_and_ward_t( compound_policy_t ):
+    """implements code generation for boost::python::with_custodian_and_ward call policies"""
     def __init__( self, custodian, ward, base=None):
         compound_policy_t.__init__( self, base )
         self._custodian = custodian
@@ -185,9 +192,11 @@
         return [ str( self.custodian ), str( self.ward ) ]
 
 def with_custodian_and_ward( custodian, ward, base=None):
+    """create boost::python::with_custodian_and_ward call policies code generator"""    
     return with_custodian_and_ward_t( custodian, ward, base )
 
 class with_custodian_and_ward_postcall_t( with_custodian_and_ward_t ):
+    """implements code generation for boost::python::with_custodian_and_ward_postcall call policies"""
     def __init__( self, custodian, ward, base=None):
         with_custodian_and_ward_t.__init__( self, custodian, ward, base )
 
@@ -195,9 +204,11 @@
         return '::boost::python::with_custodian_and_ward_postcall'
 
 def with_custodian_and_ward_postcall( custodian, ward, base=None):
+    """create boost::python::with_custodian_and_ward_postcall call policies code generator"""        
     return with_custodian_and_ward_postcall_t( custodian, ward, base )
 
 class return_value_policy_t( compound_policy_t ):
+    """implements code generation for boost::python::return_value_policy call policies"""    
     def __init__( self, result_converter_generator, base=None):
         compound_policy_t.__init__( self, base )
         self._result_converter_generator = result_converter_generator
@@ -245,6 +256,7 @@
 return_pointee_value = '::pyplusplus::call_policies::return_pointee_value'
 
 def return_value_policy( result_converter_generator, base=None):
+    """create boost::python::return_value_policy call policies code generator"""                        
     return return_value_policy_t( result_converter_generator, base )
 
 def is_return_opaque_pointer_policy( policy ):
@@ -253,7 +265,7 @@
             and policy.result_converter_generator == return_opaque_pointer
 
 class custom_call_policies_t(call_policy_t):
-    """implementation for user defined call policies"""
+    """implements code generation for user defined call policies"""
     def __init__( self, call_policies, header_file=None ):
         call_policy_t.__init__( self )
         self.__call_policies = call_policies
@@ -273,10 +285,14 @@
                             , doc="""Return name of the header file to be included""" )
 
 def custom_call_policies(call_policies, header_file=None):
-    """create custom\\user defined call policies"""
+    """create custom\\user defined call policies code generator"""
     return custom_call_policies_t(call_policies, header_file)
 
 class memory_managers:
+    """implements code generation for Py++ defined memory managers
+    
+    For complete documentation and usage example see http://language-binding.net/pyplusplus/documentation/functions/call_policies.html    
+    """
     none = 'none'
     delete_ = 'delete_'
     all = [ none, delete_ ]
@@ -289,6 +305,10 @@
         return mem_manager
 
 class convert_array_to_tuple_t( compound_policy_t ):
+    """implements code generation for Py++ defined "as_tuple" value policy
+        
+    For complete documentation and usage example see http://language-binding.net/pyplusplus/documentation/functions/call_policies.html
+    """
     def __init__( self, array_size, memory_manager, make_object_call_policies=None, base=None):
         compound_policy_t.__init__( self, base )
         self._array_size = array_size
@@ -324,7 +344,6 @@
         self._make_objec_call_policies = new_make_objec_call_policies
     make_objec_call_policies = property( _get_make_objec_call_policies, _set_make_objec_call_policies )
 
-
     def _get_name(self, function_creator):
         return '::boost::python::return_value_policy'
 
@@ -339,9 +358,14 @@
         return [ declarations.templates.join( as_tuple, as_tuple_args ) ]
     
 def convert_array_to_tuple( array_size, memory_manager, make_object_call_policies=None, base=None ):
+    """create boost::python::return_value_policy< py++::as_tuple > call policies code generator"""                        
     return convert_array_to_tuple_t( array_size, memory_manager, make_object_call_policies, base )
 
 class return_range_t( call_policy_t ):
+    """implements code generation for Py++ defined "return_range" call policies
+    
+    For complete documentation and usage example see http://language-binding.net/pyplusplus/documentation/functions/call_policies.html
+    """
     HEADER_FILE = "__return_range.pypp.hpp"
     def __init__( self, get_size_class, value_type, value_policies):
         call_policy_t.__init__( self )
@@ -384,6 +408,7 @@
         return declarations.templates.join( name, args )
     
 def return_range( function, get_size_class, value_policies=None ):
+    """create Py++ defined return_range call policies code generator"""                            
     r_type = function.return_type
     if not declarations.is_pointer( r_type ):
         raise TypeError( 'Function "%s" return type should be pointer, got "%s"'

Modified: pyplusplus_dev/pyplusplus/decl_wrappers/calldef_wrapper.py
===================================================================
--- pyplusplus_dev/pyplusplus/decl_wrappers/calldef_wrapper.py	2007-04-17 07:28:51 UTC (rev 995)
+++ pyplusplus_dev/pyplusplus/decl_wrappers/calldef_wrapper.py	2007-04-17 12:40:13 UTC (rev 996)
@@ -3,19 +3,18 @@
 # accompanying file LICENSE_1_0.txt or copy at
 # http://www.boost.org/LICENSE_1_0.txt)
 
-"""defines class that configure "callable" declaration exposing"""
+"""contains classes that allow to configure code generation for free\\member functions, operators and etc."""
 
 import os
 import user_text
 import algorithm
 import decl_wrapper
-import python_traits
 from pyplusplus import messages
 from pygccxml import declarations
 from pyplusplus import function_transformers as ft
 
 class calldef_t(decl_wrapper.decl_wrapper_t):
-    """base class for all decl_wrappers callable objects classes."""
+    """base class, for code generator configration, for function declaration classes."""
 
     BOOST_PYTHON_MAX_ARITY = 10
     """Boost.Python configuration macro value.
@@ -105,30 +104,35 @@
 
     @property 
     def non_overridable_reason( self ):
+        """returns the reason the function could not be overriden"""
         return self._non_overridable_reason
 
     def mark_as_non_overridable( self, reason ):
+        """mark this function as non-overridable
+        
+        Not all fucntions could be overrided from Python, for example virtual function
+        that returns non const reference to a member variable. Py++ allows you to
+        mark these functions and provide and explanation to the user. 
+        """
         self.overridable = False
         self._non_overridable_reason = reason
 
     @property
     def transformations(self):
-        """Get method for property 'function_transformers'.
-
-        Returns a reference to the internal list (which may be modified).
-        """
+        """return list of function transformations that should be applied on the function"""
         if None is self._transformations:
             #TODO: for trivial cases get_size( int&, int& ) Py++ should guess
             #function transformers
             self._transformations = []
         return self._transformations
 
-    def add_transformation(self, *args, **keywd):
-        """Set method for property 'function_transformers'.
+    def add_transformation(self, *transformer_creators, **keywd):
+        """add new function transformation.
 
-        args is a list of transformers
+        transformer_creators - list of transformer creators, which should be applied on the function        
+        keywd - keyword arguments for L{function_transformation_t} class initialization
         """
-        self.transformations.append( ft.function_transformation_t( self, args, **keywd ) )
+        self.transformations.append( ft.function_transformation_t( self, transformer_creators, **keywd ) )
 
     def _exportable_impl_derived( self ):
         return ''


This was sent by the SourceForge.net collaborative development platform, the world's largest Open Source development site.