[pygccxml-commit] SF.net SVN: pygccxml: [666] pyplusplus_dev/docs

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

Revision: 666
          http://svn.sourceforge.net/pygccxml/?rev=666&view=rev
Author:   roman_yakovenko
Date:     2006-10-17 08:03:57 -0700 (Tue, 17 Oct 2006)

Log Message:
-----------
updating documentation

Modified Paths:
--------------
    pyplusplus_dev/docs/bpl_lessons_learned/smart_ptrs/bindings.cpp
    pyplusplus_dev/docs/bpl_lessons_learned/smart_ptrs/classes.hpp
    pyplusplus_dev/docs/bpl_lessons_learned/smart_ptrs/sconstruct
    pyplusplus_dev/docs/documentation/functions/call_policies.rest
    pyplusplus_dev/docs/documentation/functions/default_args.rest
    pyplusplus_dev/docs/documentation/functions/functions.rest
    pyplusplus_dev/docs/documentation/functions/overloading.rest

Modified: pyplusplus_dev/docs/bpl_lessons_learned/smart_ptrs/bindings.cpp
===================================================================
--- pyplusplus_dev/docs/bpl_lessons_learned/smart_ptrs/bindings.cpp	2006-10-16 21:24:52 UTC (rev 665)
+++ pyplusplus_dev/docs/bpl_lessons_learned/smart_ptrs/bindings.cpp	2006-10-17 15:03:57 UTC (rev 666)
@@ -1,8 +1,3 @@
-// Copyright 2004 Roman Yakovenko.
-// Distributed under the Boost Software License, Version 1.0. (See
-// accompanying file LICENSE_1_0.txt or copy at
-// http://www.boost.org/LICENSE_1_0.txt)
-
 #include "boost/python.hpp"
 #include "classes.hpp"
 
@@ -11,11 +6,13 @@
 namespace boost{ namespace python{
 
     //We need to tell Boost.Python how to work with your smart pointer.
+    //Short explanation:
+    //  "get_pointer" extracts the pointer to the object it manages.
+    //  "pointee" extracts the type of the object, smart pointer manages.
+    
     //You can read more about this functionality in the reference manual:
     //http://boost.org/libs/python/doc/v2/pointee.html .
-    //In general 
-    //    get_pointer extracts the pointer to the object it manages.
-    //    pointee extracts the type of the object smart pointer manages.
+
     template<class T>
     inline T * get_pointer(smart_ptr_t<T> const& p){
         return p.get();
@@ -86,8 +83,9 @@
 
     //Register implicit conversion between smart pointers. Boost.Python library
     //can not discover relationship between classes.This will allow Boost.Python
-    //to treat right functions, which expect to get as argument smart_ptr_t< base_i >
-    //class instance.
+    //to treat right the functions, which expect to get as argument 
+    //smart_ptr_t< base_i > class instance, when smart_ptr_t< derived from base_i > 
+    //class instance is passed.
     //For more information about implicitly_convertible see the documentation:
     //http://boost.org/libs/python/doc/v2/implicit.html .
     bp::implicitly_convertible< smart_ptr_t< base_wrapper_t >, smart_ptr_t< base_i > >();
@@ -103,7 +101,7 @@
     //in Python, which derive from the derived_t class.
         .def( "get_value", &derived_t::get_value, &derived_wrapper_t::default_get_value );
 
-    //Nothing special, just registering all existing conversion.
+    //Now register all existing conversion:
     bp::implicitly_convertible< smart_ptr_t< derived_wrapper_t >, smart_ptr_t< derived_t > >();
     bp::implicitly_convertible< smart_ptr_t< derived_t >, smart_ptr_t< base_i > >();
     bp::implicitly_convertible< derived_ptr_t, smart_ptr_t< derived_t > >();

Modified: pyplusplus_dev/docs/bpl_lessons_learned/smart_ptrs/classes.hpp
===================================================================
--- pyplusplus_dev/docs/bpl_lessons_learned/smart_ptrs/classes.hpp	2006-10-16 21:24:52 UTC (rev 665)
+++ pyplusplus_dev/docs/bpl_lessons_learned/smart_ptrs/classes.hpp	2006-10-17 15:03:57 UTC (rev 666)
@@ -1,7 +1,6 @@
 #ifndef classes_11_11_2006
 #define classes_11_11_2006
 
-
 #include "smart_ptr.h"
 
 struct base_i{
@@ -68,14 +67,16 @@
 }
 
 
-//Next function could be exposed, but it could not be solved
+//Next function could be exposed, but it could not be called from Python, when
+//the argument is instance of derived class.
+//
 //This is the explanation David Abrahams gave:
-//Naturally; there is no instance of smart_ptr_t<base_i> anywhere in the
-//Python object for the reference to bind to. The rules are the same as in C++:
+//  Naturally; there is no instance of smart_ptr_t<base_i> anywhere in the
+//  Python object for the reference to bind to. The rules are the same as in C++:
 //
-//  int f(smart_ptr_t<base>& x) { return 0; }
+//  int f(smart_ptr_t<base>& x);
 //  smart_ptr_t<derived> y;
-//  int z = f(y);                // fails to compile
+//  int z = f(y);               // fails to compile
 
 inline int
 ref_get_value( smart_ptr_t< base_i >& a ){

Modified: pyplusplus_dev/docs/bpl_lessons_learned/smart_ptrs/sconstruct
===================================================================
--- pyplusplus_dev/docs/bpl_lessons_learned/smart_ptrs/sconstruct	2006-10-16 21:24:52 UTC (rev 665)
+++ pyplusplus_dev/docs/bpl_lessons_learned/smart_ptrs/sconstruct	2006-10-17 15:03:57 UTC (rev 666)
@@ -1,3 +1,4 @@
+#scons build script
 SharedLibrary( target=r'custom_sptr'
     , source=[ r'bindings.cpp' ]
     , LIBS=[ r"boost_python" ]
@@ -3,5 +4,4 @@
     , LIBPATH=[ r"/home/roman/boost_cvs/bin",r"" ]
     , CPPPATH=[ r"/home/roman/boost_cvs",r"/usr/include/python2.4" ]
-    , CCFLAGS=[ '-DBOOST_PYTHON_TRACE_REGISTRY' ]
     , SHLIBPREFIX=''
     , SHLIBSUFFIX='.so'

Modified: pyplusplus_dev/docs/documentation/functions/call_policies.rest
===================================================================
--- pyplusplus_dev/docs/documentation/functions/call_policies.rest	2006-10-16 21:24:52 UTC (rev 665)
+++ pyplusplus_dev/docs/documentation/functions/call_policies.rest	2006-10-17 15:03:57 UTC (rev 666)
@@ -8,11 +8,11 @@
 Introduction
 ------------
 
-`Boost.Python`_ has a `nice introduction`__ in the tutorials about call policies.
-Also you can find more formal definition - `CallPolicies Concept`_ . 
+`Boost.Python`_ has a `nice introduction`__ to call policies. `"Call policies concept"`_
+document will provide you with formal definition.
 
 .. __ : http://boost.org/libs/python/doc/tutorial/doc/html/python/functions.html#python.call_policies
-.. _`CallPolicies Concept` : http://boost.org/libs/python/doc/v2/CallPolicies.html#CallPolicies-concept
+.. _`"Call policies concept"` : http://boost.org/libs/python/doc/v2/CallPolicies.html#CallPolicies-concept
 
 ------
 Syntax
@@ -60,51 +60,54 @@
     
     mb = module_builder.module_builder_t( ... )
     mb.free_function( 'return_second_arg' ).call_policies = call_policies.return_arg( 2 )
+    #---------------------------------------^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
     
     mb.member_function( 'do_smth' ).call_policies = call_policies.return_self()
+    #-------------------------------^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
     
-    mb.calldef( 'get_opaque' ).call_policies \
+    mb.calldef( 'get_opaque' ).call_policies 
         = call_policies.return_value_policy( call_policies.return_opaque_pointer )
 
 --------
 Defaults
 --------
 
-`Py++`_ is able to "guess" few call policies, base on analysis of return type:
+`Py++`_ is able to "guess" few call policies, base on analysis of return type
+and\\or operator name:
 
 * ``default_call_policies``:
 
-  * `Python`_ immutable type by value: C++ fundamental types, ``std::string``, enumerations
+  * `Python`_ immutable type returned by value: C++ fundamental types, ``std::string``, enumerations
   
-  *  user defined type ( class ) by value
+  *  user-defined type ( class ) returned by value
   
-  * ``const char*``
+  * return type is ``const char*``
 
 * ``return_value_policy``
   
   * ``return_opaque_pointer``
   
-    * ``void*`` 
+    * return type is ``void*`` 
   
-    * ``const void*``
+    * return type is ``const void*``
   
   * ``copy_const_reference``
 
-    * ``const T&``
+    * return type is ``const T&``
     
     * for member ``operator[]`` that returns const reference to immutable type
   
   * ``return_by_value``
 
-    * ``const wchar_t*``
+    * return type is ``const wchar_t*``
     
   * ``copy_non_const_reference``
   
-    * ``T&``, for member ``operator[]`` that returns reference to immutable type
+    * return type is ``T&``, for member ``operator[]`` that returns reference to immutable type
   
   * ``return_internal_reference``
   
-    * ``T&``, for member ``operator[]``
+    * return type is ``T&``, for member ``operator[]``
 
 ---------------------
 Missing call policies
@@ -131,9 +134,9 @@
 ------------
 
 ``return_value_policy( return_opaque_pointer )`` is a special policy for `Boost.Python`_.
-In this case, it requieres from an user to define specializations for the 
+In this case, it requieres from you to define specialization for the 
 ``boost::python::type_id`` function on the type pointed to by returned pointer. 
-`Py++`_ will generate the requiered code.
+`Py++`_ will generate the required code. 
 
 For more information about the call policy please refer to `Boost.Python`_
 `documentation`_.
@@ -141,8 +144,6 @@
 .. _`documentation` : http://boost.org/libs/python/doc/v2/return_opaque_pointer.html 
 
 
-
-
 .. _`Py++` : ./../pyplusplus.html
 .. _`Boost.Python`: http://www.boost.org/libs/python/doc/index.html
 .. _`Python`: http://www.python.org

Modified: pyplusplus_dev/docs/documentation/functions/default_args.rest
===================================================================
--- pyplusplus_dev/docs/documentation/functions/default_args.rest	2006-10-16 21:24:52 UTC (rev 665)
+++ pyplusplus_dev/docs/documentation/functions/default_args.rest	2006-10-17 15:03:57 UTC (rev 666)
@@ -39,8 +39,8 @@
             , ( bp::arg("a")=(int)(12) ) );  
   }
 
-This approach brings another additional value: keyword arguments. Your users
-will be able to call function ``f`` like this:
+The additional value of the approach is keyword arguments. You will be able to 
+call function ``f`` like this:
 
 .. code-block:: Python
 
@@ -52,17 +52,24 @@
 ----------------------------
 
 ``BOOST_PYTHON_FUNCTION_OVERLOADS`` and ``BOOST_PYTHON_MEMBER_FUNCTION_OVERLOADS``
-macros help to deal with default values. You can turn ``use_overload_macro``
-to ``True`` as shown in `overloading`_ document.
+macros can help to deal with default values too. You can turn ``use_overload_macro``
+to ``True``:
 
-.. _`overloading` : ./overloading.html 
+.. code-block:: Python
 
+  import module_builder
+  
+  mb = module_builder.module_builder_t( ... )
+  x = mb.class_( "X" )
+  x.member_function( "f" ).use_overload_macro = True
+  #------------------------^^^^^^^^^^^^^^^^^^^^^^^^^
+
 --------------------------
 Registration order problem
 --------------------------
 
-There are different trades-off between these approaches. In general you should
-use the first one, untill you have "registration order" problem:
+There is different trades-off between these approaches. In general you should
+use the first one, until you have "registration order" problem:
 
 .. code-block:: C++
 
@@ -88,30 +95,51 @@
           
   }
 
-These module could not be loaded, because the expression ``arg("s1")=S1()``
-requieres ``S1`` struct to be registered. `GCC-XML`_ reports default arguments 
-as strings. `Py++`_ doesn't have enough information to generate code with the 
-right class registration order.
+The good news is that it is very easy to identify the problem: the module could 
+not be loaded. The main reason is that expression ``arg("s1")=S1()`` requires 
+``S1`` struct to be registered. `GCC-XML`_ reports default arguments as strings. 
+`Py++`_ doesn't have enough information to generate code with the right class 
+registration order. In this case you have to instruct `Py++`_ to use macros:
 
+.. code-block:: Python
 
-Unfortunatelly these macros have some limitations:
+  import module_builde
+  
+  mb = module_builder.module_builder_t( ... )
+  s2 = mb.class_( "S2" )
+  s2.member_function( "do_smth" ).use_overload_macro = True
 
-1. The overloaded functions must have a common sequence of initial arguments.
+When you switch to macros, than:
 
-2. You will not be able to override virtual functions in `Python`_.
+* You will not be able to override virtual functions in `Python`_.
 
-3. You will not be able to use "named" arguments.
+* You will not be able to use "named" arguments.
 
-4. You will not be able to set the functions documentation.
+* You will not be able to set the functions documentation.
 
-Nevertheless these limitations the macros becomes very useful when you have 
-"registration order" problem with default arguments.
+Special case
+------------
 
+Class constructors are special case:
 
+.. code-block:: C++
 
+  struct S1;
+  struct S2;
+  
+  struct S1{
+      S1( S2* s2=0 );
+  };
+  
+  struct S2{
+      S2( S1 s1=S1() );
+  };
 
-`Py++`_ needs your help to generate right code:
 
+You cannot use same work around and `Py++`_ ( version 0.8.2 ) could not help you.
+The use case presented here is a little bit esoteric. If you have such use case
+and you cannot change the source code, consider contacting `Py++`_ developers.
+I am sure we will be able to help you.
 
 
 .. _`Py++` : ./../pyplusplus.html

Modified: pyplusplus_dev/docs/documentation/functions/functions.rest
===================================================================
--- pyplusplus_dev/docs/documentation/functions/functions.rest	2006-10-16 21:24:52 UTC (rev 665)
+++ pyplusplus_dev/docs/documentation/functions/functions.rest	2006-10-17 15:03:57 UTC (rev 666)
@@ -10,7 +10,7 @@
 
 `Boost.Python`_ provides very rich interface to expose functions and operators.
 This section of documentation will explain how to configure `Py++`_ in order
-to export your code using desired `Boost.Python`_ functionality.
+to export your functions, using desired `Boost.Python`_ functionality.
 
 
 .. _`Py++` : ./../pyplusplus.html

Modified: pyplusplus_dev/docs/documentation/functions/overloading.rest
===================================================================
--- pyplusplus_dev/docs/documentation/functions/overloading.rest	2006-10-16 21:24:52 UTC (rev 665)
+++ pyplusplus_dev/docs/documentation/functions/overloading.rest	2006-10-17 15:03:57 UTC (rev 666)
@@ -8,7 +8,7 @@
 Introduction
 ------------
 
-Things get a little bit complex, when you should export overloaded functions.
+Things get a little bit complex, when you have to export overloaded functions.
 In general the solution is to explicitly say to compiler what function you
 want to export, by specifying its type. Before we proceed, please take a look
 on next class:
@@ -37,7 +37,7 @@
 
 .. __ : http://boost.org/libs/python/doc/tutorial/doc/html/python/functions.html#python.overloading
 
-There are few approaches, which you can use in order to exort the functions.
+There are few approaches, which you can use in order to export the functions.
 
 -------------------
 Do nothing approach
@@ -66,9 +66,6 @@
             , ( bp::arg("a"), bp::arg("b"), bp::arg("c") ) );
   }
 
-From my experience, this approach works pretty well and in most cases the only
-customization you should do on exported function is to setup right call policies.
-
 --------------------------------
 "create_with_signature" approach
 --------------------------------
@@ -79,15 +76,12 @@
 Overloaded template function
 ----------------------------
 
-I am sure you already know next facts, but still I want to remind them:
+I am sure you already know next fact, but still I want to remind it:
 
-1. `GCC-XML`_ doesn't report about uninstantiated templates
+* `GCC-XML`_ doesn't report about un-instantiated templates
 
-2. `Boost.Python`_ is able to export only template instantiation
+It is very important to understand it. Lets take a look on next source code:
 
-It is very important to understand the first fact. Lets take a look on next source
-code:
-
 .. code-block:: C++
 
   struct Y{
@@ -101,7 +95,7 @@
 
 If you didn't instantiate( use ) ``do_smth`` member function, than `GCC-XML`_
 will not report it. As a result, `Py++`_ will not be aware of the fact that 
-``do_smth`` is an overloaded function. To make the long story short the generated
+``do_smth`` is an overloaded function. To make the long story short, the generated
 code will not compile. You have to instruct `Py++`_ to generate code, which 
 contains function type:
 
@@ -125,11 +119,19 @@
 Code modification - the weakness of the "do nothing" approach. We live in the 
 dynamic world. You can create bindings for a project, but a month letter, the 
 project developers will add a new function to the exported class. Lets assume 
-that the function will introduce overloading. If ``create_with_signature`` has 
-``False`` as a value, than the previously generated code will not compile. My 
-advise to you: explicitly set ``create_with_signature`` to ``True``. It will 
-save your time in future.
+that the new function will introduce overloading. If ``create_with_signature`` 
+has ``False`` as a value, than the previously generated code will not compile 
+and you will have to run code generator one more time. 
 
+Consider to explicitly set ``create_with_signature`` to ``True``. It will save 
+your and your users time in future.
+
+.. code-block:: Python
+
+  mb = module_builder_t( ... )
+  mb.calldefs().create_with_signature = True
+
+
 ------------------------
 Overloading using macros
 ------------------------
@@ -141,7 +143,7 @@
 
 * ``BOOST_PYTHON_MEMBER_FUNCTION_OVERLOADS``
 
-`Boost.Python`_ tutorials contains an `explanation`_ about this macros.
+`Boost.Python`_ tutorials contain an `explanation`_ about this macros.
 
 .. _`explanation` : http://boost.org/libs/python/doc/tutorial/doc/html/python/functions.html#python.auto_overloading
 


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