More comments...

[SVN r14811]

include/boost/python/class.hpp

@@ -135,21 +135,13 @@ class class_ : public objects::class_base
     template <typename DerivedT, typename SigT>
     self& def(detail::func_stubs_base<DerivedT> const& stubs, signature<SigT> sig)
     {
-        //  JDG 8-12-2002
+        //  convert sig to a type_list (see signature.hpp) and call
+        //  detail::define_with_defaults passing in the stubs (see defaults_gen.hpp),
+        //  this instance, and the converted sig type_list.
         detail::define_with_defaults(stubs.derived(), *this, detail::get_signature(sig));
         return *this;
     }
 
-/*
-    template <typename DerivedT, typename ArgsT>
-    self& def(detail::func_stubs_base<DerivedT> const& stubs, ArgsT args)
-    {
-        //  JDG 8-12-2002
-        detail::define_with_defaults(stubs.derived(), *this, args);
-        return *this;
-    }
-*/
-
     // Define the constructor with the given Args, which should be an
     // MPL sequence of types.
     template <class Args>

include/boost/python/detail/defaults_def.hpp

@@ -66,10 +66,10 @@ BOOST_PP_REPEAT(BOOST_PYTHON_MAX_ARITY, BPL_IMPL_STUB_FUNC_DEF, BOOST_PP_EMPTY)
 //
 //  define_with_defaults_helper<N>
 //
-//  This helper template struct does the actual recursive definition
+//  This helper template struct does the actual recursive definition.
 //  There's a generic version define_with_defaults_helper<N> and a
 //  terminal case define_with_defaults_helper<0>. The struct and its
-//  specialization has a sole static member function def that expect:
+//  specialization has a sole static member function def that expects:
 //
 //      1. char const* name:    a python function name
 //      2. StubsT:              a function stubs struct (see defaults_gen.hpp)
@@ -109,6 +109,20 @@ BOOST_PP_REPEAT(BOOST_PYTHON_MAX_ARITY, BPL_IMPL_STUB_FUNC_DEF, BOOST_PP_EMPTY)
         }
     };
 
+///////////////////////////////////////////////////////////////////////////////
+//
+//  define_with_defaults
+//
+//  This is the main entry point. This function recursively defines all
+//  stub functions of StubT (see defaults_gen.hpp) in HolderT holder which
+//  can be either a python::class_ or a python::module. The sig argument
+//  is a typelist that specifies the return type, the class (for member
+//  functions, and the arguments. Here are some SigT examples:
+//
+//      int foo(int)        mpl::type_list<int, int>
+//      void bar(int, int)  mpl::type_list<void, int, int>
+//      void C::foo(int)    mpl::type_list<void, C, int>
+//
 ///////////////////////////////////////////////////////////////////////////////
     template <typename StubsT, typename HolderT, typename SigT>
     inline void

include/boost/python/module.hpp

@@ -74,20 +74,12 @@ class module : public detail::module_base
     template <typename DerivedT, typename SigT>
     module& def(detail::func_stubs_base<DerivedT> const& stubs, signature<SigT> sig)
     {
-        //  JDG 8-12-2002
+        //  convert sig to a type_list (see signature.hpp) and call
+        //  detail::define_with_defaults passing in the stubs (see defaults_gen.hpp),
+        //  this instance, and the converted sig type_list.
         detail::define_with_defaults(stubs.derived(), *this, detail::get_signature(sig));
         return *this;
     }
-
-/*
-    template <typename DerivedT, typename ArgsT>
-    module& def(detail::func_stubs_base<DerivedT> const& stubs, ArgsT args)
-    {
-        //  JDG 8-12-2002
-        detail::define_with_defaults(stubs.derived(), *this, args);
-        return *this;
-    }
-*/
 };
 
 //

include/boost/python/signature.hpp

@@ -20,6 +20,20 @@
 ///////////////////////////////////////////////////////////////////////////////
 namespace boost { namespace python {
 
+///////////////////////////////////////////////////////////////////////////////
+//
+//  signature
+//
+//  This template struct acts as a type holder for the signature of a
+//  function or member function. This struct is used to pass in the
+//  return type, class (for member functions) and arguments of a
+//  function or member function. Examples:
+//
+//      signature<int(*)(int)>          int foo(int)
+//      signature<void(*)(int, int)>    void foo(int, int)
+//      signature<void(C::*)(int)>      void C::foo(int, int)
+//
+///////////////////////////////////////////////////////////////////////////////
 template <typename T>
 struct signature {};
 
@@ -34,6 +48,27 @@ namespace detail {
     /**/
 #endif
 
+///////////////////////////////////////////////////////////////////////////////
+//
+//  The following macros generate expansions for:
+//
+//      template <typename RT, typename T0... typename TN>
+//      inline boost::mpl::type_list<RT, T0...TN>
+//      get_signature(signature<RT(*)(T0...TN)>)
+//      {
+//          return boost::mpl::type_list<RT, T0...TN>();
+//      }
+//
+//      template <typename RT, typename ClassT, typename T0... typename TN>
+//      inline boost::mpl::type_list<RT, ClassT, T0...TN>
+//      get_signature(signature<RT(ClassT::*)(T0...TN))>)
+//      {
+//          return boost::mpl::type_list<RT, ClassT, T0...TN>();
+//      }
+//
+//  These functions extract the return type, class (for member functions)
+//  and arguments of the input signature and stuffs them in an mpl::type_list.
+//
 ///////////////////////////////////////////////////////////////////////////////
 #define BPL_IMPL_TEMPLATE_GEN(INDEX, DATA)  typename BOOST_PP_CAT(T, INDEX)