From 5933fdbf3913040e751736e5f8df2aaf0065b000 Mon Sep 17 00:00:00 2001 From: Jonathan Brandmeyer Date: Sat, 22 Jan 2005 21:41:37 +0000 Subject: [PATCH] Add docstring support for non-static properties. [SVN r26814] --- doc/v2/class.html | 28 ++++++++++++----------- include/boost/python/class.hpp | 33 ++++++++++++++------------- include/boost/python/object/class.hpp | 6 +++-- src/object/class.cpp | 10 ++++---- test/properties.cpp | 3 +++ test/properties.py | 5 ++++ 6 files changed, 50 insertions(+), 35 deletions(-) diff --git a/doc/v2/class.html b/doc/v2/class.html index a055e5a5..5505dc5c 100644 --- a/doc/v2/class.html +++ b/doc/v2/class.html @@ -269,9 +269,10 @@ namespace boost { namespace python // property creation template <class Get> - void add_property(char const* name, Get const& fget); + void add_property(char const* name, Get const& fget, char const* doc=0); template <class Get, class Set> - void add_property(char const* name, Get const& fget, Set const& fset); + void add_property( + char const* name, Get const& fget, Set const& fset, char const* doc=0); template <class Get> void add_static_property(char const* name, Get const& fget); @@ -564,14 +565,15 @@ class_& setattr(char const* name, U const& u); 
 template <class Get>
-void add_property(char const* name, Get const& fget);
+void add_property(char const* name, Get const& fget, char const* doc=0);
 template <class Get, class Set>
-void add_property(char const* name, Get const& fget, Set const& fset);
+void add_property(
+	char const* name, Get const& fget, Set const& fset, char const* doc=0);
Requires: name is an ntbs which conforms to Python's ntbs which conform to Python's identifier naming rules.
@@ -580,9 +582,9 @@ void add_property(char const* name, Get const& fget, Set const& fset); class instance, passing object(fget) (and object(fset) in the - second form) to its constructor, then adds that property to the Python - class object under construction with the given attribute - name. + second form) with an (optional) docstring doc to its constructor, + then adds that property to the Python class object under construction + with the given attribute name.
Returns: *this
@@ -622,7 +624,7 @@ void add_static_property(char const* name, Get const& fget, Set const& f 
 template <class D>
-class_& def_readonly(char const* name, D T::*pm);
+class_& def_readonly(char const* name, D T::*pm, char const* doc=0);
 template <class D>
 class_& def_readonly(char const* name, D const& d);
@@ -631,14 +633,14 @@ class_& def_readonly(char const* name, D const& d);
Requires: name is an ntbs which conforms to Python's identifier - naming rules.
+ naming rules. doc is also an ntbs.
Effects:
 this->add_property(name, make_getter(pm));
+"data_members.html#make_getter-spec">make_getter(pm), doc);
and 
@@ -657,7 +659,7 @@ this->add_static_property(name, 
 
 template <class D>
-class_& def_readwrite(char const* name, D T::*pm);
+class_& def_readwrite(char const* name, D T::*pm, char const* doc=0);
 template <class D>
 class_& def_readwrite(char const* name, D& d);
 

@@ -669,7 +671,7 @@ class_& def_readwrite(char const* name, D& d);
 
 this->add_property(name, make_getter(pm), make_setter(pm));
+"data_members.html#make_setter-spec">make_setter(pm), doc);
 

         and 
 
diff --git a/include/boost/python/class.hpp b/include/boost/python/class.hpp
index e00afcdc..c249cc17 100644
--- a/include/boost/python/class.hpp
+++ b/include/boost/python/class.hpp
@@ -277,41 +277,42 @@ class class_ : public objects::class_base
     // Data member access
     //
     template 
-    self& def_readonly(char const* name, D const& d)
+    self& def_readonly(char const* name, D const& d, char const* doc=0)
     {
-        return this->def_readonly_impl(name, d BOOST_PYTHON_DATA_MEMBER_HELPER(D));
+        return this->def_readonly_impl(name, d BOOST_PYTHON_DATA_MEMBER_HELPER(D), doc);
     }
 
     template 
-    self& def_readwrite(char const* name, D const& d)
+    self& def_readwrite(char const* name, D const& d, char const* doc=0)
     {
-        return this->def_readwrite_impl(name, d BOOST_PYTHON_DATA_MEMBER_HELPER(D));
+        return this->def_readwrite_impl(name, d BOOST_PYTHON_DATA_MEMBER_HELPER(D), doc);
     }
     
     template 
-    self& def_readonly(char const* name, D& d)
+    self& def_readonly(char const* name, D& d, char const* doc=0)
     {
-        return this->def_readonly_impl(name, d BOOST_PYTHON_DATA_MEMBER_HELPER(D));
+        return this->def_readonly_impl(name, d BOOST_PYTHON_DATA_MEMBER_HELPER(D), doc);
     }
 
     template 
-    self& def_readwrite(char const* name, D& d)
+    self& def_readwrite(char const* name, D& d, char const* doc=0)
     {
-        return this->def_readwrite_impl(name, d BOOST_PYTHON_DATA_MEMBER_HELPER(D));
+        return this->def_readwrite_impl(name, d BOOST_PYTHON_DATA_MEMBER_HELPER(D), doc);
     }
 
     // Property creation
     template 
-    self& add_property(char const* name, Get fget)
+    self& add_property(char const* name, Get fget, char const* docstr = 0)
     {
-        base::add_property(name, this->make_getter(fget));
+        base::add_property(name, this->make_getter(fget), docstr);
         return *this;
     }
 
     template 
-    self& add_property(char const* name, Get fget, Set fset)
+    self& add_property(char const* name, Get fget, Set fset, char const* docstr = 0)
     {
-        base::add_property(name, this->make_getter(fget), this->make_setter(fset));
+        base::add_property(
+            name, this->make_getter(fget), this->make_setter(fset), docstr);
         return *this;
     }
         
@@ -421,16 +422,16 @@ class class_ : public objects::class_base
     
     template 
     self& def_readonly_impl(
-        char const* name, D B::*pm_ BOOST_PYTHON_YES_DATA_MEMBER)
+        char const* name, D B::*pm_ BOOST_PYTHON_YES_DATA_MEMBER, char const* doc)
     {
-        return this->add_property(name, pm_);
+        return this->add_property(name, pm_, doc);
     }
 
     template 
     self& def_readwrite_impl(
-        char const* name, D B::*pm_ BOOST_PYTHON_YES_DATA_MEMBER)
+        char const* name, D B::*pm_ BOOST_PYTHON_YES_DATA_MEMBER, char const* doc)
     {
-        return this->add_property(name, pm_, pm_);
+        return this->add_property(name, pm_, pm_, doc);
     }
 
     template 
diff --git a/include/boost/python/object/class.hpp b/include/boost/python/object/class.hpp
index 1357e6fe..6aad45e7 100644
--- a/include/boost/python/object/class.hpp
+++ b/include/boost/python/object/class.hpp
@@ -34,8 +34,10 @@ struct BOOST_PYTHON_DECL class_base : python::api::object
     void enable_pickling_(bool getstate_manages_dict);
 
  protected:
-    void add_property(char const* name, object const& fget);
-    void add_property(char const* name, object const& fget, object const& fset);
+    void add_property(
+        char const* name, object const& fget, char const* docstr);
+    void add_property(char const* name, 
+        object const& fget, object const& fset, char const* docstr);
 
     void add_static_property(char const* name, object const& fget);
     void add_static_property(char const* name, object const& fget, object const& fset);
diff --git a/src/object/class.cpp b/src/object/class.cpp
index 89890b96..191249e9 100644
--- a/src/object/class.cpp
+++ b/src/object/class.cpp
@@ -535,20 +535,22 @@ namespace objects
       this->attr("__instance_size__") = instance_size;
   }
   
-  void class_base::add_property(char const* name, object const& fget)
+  void class_base::add_property(
+    char const* name, object const& fget, char const* docstr)
   {
       object property(
           (python::detail::new_reference)
-              PyObject_CallFunction((PyObject*)&PyProperty_Type, "O", fget.ptr()));
+              PyObject_CallFunction((PyObject*)&PyProperty_Type, "Osss", fget.ptr(), 0, 0, docstr));
       
       this->setattr(name, property);
   }
 
-  void class_base::add_property(char const* name, object const& fget, object const& fset)
+  void class_base::add_property(
+    char const* name, object const& fget, object const& fset, char const* docstr)
   {
       object property(
           (python::detail::new_reference)
-              PyObject_CallFunction((PyObject*)&PyProperty_Type, "OO", fget.ptr(), fset.ptr()));
+              PyObject_CallFunction((PyObject*)&PyProperty_Type, "OOss", fget.ptr(), fset.ptr(), 0, docstr));
       
       this->setattr(name, property);
   }
diff --git a/test/properties.cpp b/test/properties.cpp
index e74fc2ff..d338beb9 100755
--- a/test/properties.cpp
+++ b/test/properties.cpp
@@ -64,8 +64,11 @@ BOOST_PYTHON_MODULE(properties_ext)
     class_("X", init() )
         //defining read only property
         .add_property( "value_r", &X::get_value )
+        .add_property( "value_r_ds", &X::get_value, "value_r_ds is read-only")
         //defining read \ write property 
         .add_property( "value_rw", &X::get_value, &X::set_value )
+        .add_property( "value_rw_ds", &X::get_value, &X::set_value, 
+            "value_rw_ds is read-write")
         //defining read \ write property using make_getter and make_setter
         .add_property( "value_direct", 
                         make_getter( &X::m_value, return_by_value_t() ),
diff --git a/test/properties.py b/test/properties.py
index beccf178..720fb859 100644
--- a/test/properties.py
+++ b/test/properties.py
@@ -79,6 +79,11 @@ after creating second intstance of X instances count is 2
 
 >>> del x2
 >>> assert x1.instance_count == 1
+
+>>> assert properties.X.value_r_ds.__doc__ == "value_r_ds is read-only"
+
+>>> assert properties.X.value_rw_ds.__doc__ == "value_rw_ds is read-write"
+
 """
 
 #import sys; sys.path.append(r'P:\Actimize4.0\smart_const\py_smart_const___Win32_Debug')