Skip to content

Commit 5933fdb

Browse files
author
Jonathan Brandmeyer
committed
Add docstring support for non-static properties.
[SVN r26814]
1 parent 4c21a29 commit 5933fdb

6 files changed

Lines changed: 50 additions & 35 deletions

File tree

‎doc/v2/class.html‎

Lines changed: 15 additions & 13 deletions
Original file line numberDiff line numberDiff line change
@@ -269,9 +269,10 @@ <h4><a name="class_-spec-synopsis"></a>Class template <code>class_</code>
269269

270270
// property creation
271271
template &lt;class Get&gt;
272-
void add_property(char const* name, Get const&amp; fget);
272+
void add_property(char const* name, Get const&amp; fget, char const* doc=0);
273273
template &lt;class Get, class Set&gt;
274-
void add_property(char const* name, Get const&amp; fget, Set const&amp; fset);
274+
void add_property(
275+
char const* name, Get const&amp; fget, Set const&amp; fset, char const* doc=0);
275276

276277
template &lt;class Get&gt;
277278
void add_static_property(char const* name, Get const&amp; fget);
@@ -564,14 +565,15 @@ <h4><a name="class_-spec-modifiers"></a>Class template
564565

565566
<pre>
566567
template &lt;class Get&gt;
567-
void add_property(char const* name, Get const&amp; fget);
568+
void add_property(char const* name, Get const&amp; fget, char const* doc=0);
568569
template &lt;class Get, class Set&gt;
569-
void add_property(char const* name, Get const&amp; fget, Set const&amp; fset);
570+
void add_property(
571+
char const* name, Get const&amp; fget, Set const&amp; fset, char const* doc=0);
570572
</pre>
571573

572574
<dl class="function-semantics">
573575
<dt><b>Requires:</b> <code>name</code> is an <a href=
574-
"definitions.html#ntbs">ntbs</a> which conforms to Python's <a href=
576+
"definitions.html#ntbs">ntbs</a> which conform to Python's <a href=
575577
"http://www.python.org/doc/current/ref/identifiers.html">identifier
576578
naming rules</a>.</dt>
577579

@@ -580,9 +582,9 @@ <h4><a name="class_-spec-modifiers"></a>Class template
580582
class instance, passing <code><a href=
581583
"object.html#object-spec-ctors">object</a>(fget)</code> (and <code><a
582584
href="object.html#object-spec-ctors">object</a>(fset)</code> in the
583-
second form) to its constructor, then adds that property to the Python
584-
class object under construction with the given attribute
585-
<code>name</code>.</dt>
585+
second form) with an (optional) docstring <code>doc</code> to its constructor,
586+
then adds that property to the Python class object under construction
587+
with the given attribute <code>name</code>.</dt>
586588

587589
<dt><b>Returns:</b> <code>*this</code></dt>
588590

@@ -622,7 +624,7 @@ <h4><a name="class_-spec-modifiers"></a>Class template
622624
<br>
623625
<pre>
624626
template &lt;class D&gt;
625-
class_&amp; def_readonly(char const* name, D T::*pm);
627+
class_&amp; def_readonly(char const* name, D T::*pm, char const* doc=0);
626628
template &lt;class D&gt;
627629
class_&amp; def_readonly(char const* name, D const&amp; d);
628630
</pre>
@@ -631,14 +633,14 @@ <h4><a name="class_-spec-modifiers"></a>Class template
631633
<dt><b>Requires:</b> <code>name</code> is an <a href=
632634
"definitions.html#ntbs">ntbs</a> which conforms to Python's <a href=
633635
"http://www.python.org/doc/current/ref/identifiers.html">identifier
634-
naming rules</a>.</dt>
636+
naming rules</a>. <code>doc</code> is also an ntbs.</dt>
635637

636638
<dt><b>Effects:</b></dt>
637639

638640
<dd>
639641
<pre>
640642
this-&gt;add_property(name, <a href=
641-
"data_members.html#make_getter-spec">make_getter</a>(pm));
643+
"data_members.html#make_getter-spec">make_getter</a>(pm), doc);
642644
</pre>
643645
and
644646
<pre>
@@ -657,7 +659,7 @@ <h4><a name="class_-spec-modifiers"></a>Class template
657659
</dl>
658660
<pre>
659661
template &lt;class D&gt;
660-
class_&amp; def_readwrite(char const* name, D T::*pm);
662+
class_&amp; def_readwrite(char const* name, D T::*pm, char const* doc=0);
661663
template &lt;class D&gt;
662664
class_&amp; def_readwrite(char const* name, D&amp; d);
663665
</pre>
@@ -669,7 +671,7 @@ <h4><a name="class_-spec-modifiers"></a>Class template
669671
<pre>
670672
this-&gt;add_property(name, <a href=
671673
"data_members.html#make_getter-spec">make_getter</a>(pm), <a href=
672-
"data_members.html#make_setter-spec">make_setter</a>(pm));
674+
"data_members.html#make_setter-spec">make_setter</a>(pm), doc);
673675
</pre>
674676
and
675677
<pre>

‎include/boost/python/class.hpp‎

Lines changed: 17 additions & 16 deletions
Original file line numberDiff line numberDiff line change
@@ -277,41 +277,42 @@ class class_ : public objects::class_base
277277
// Data member access
278278
//
279279
template <class D>
280-
self& def_readonly(char const* name, D const& d)
280+
self& def_readonly(char const* name, D const& d, char const* doc=0)
281281
{
282-
return this->def_readonly_impl(name, d BOOST_PYTHON_DATA_MEMBER_HELPER(D));
282+
return this->def_readonly_impl(name, d BOOST_PYTHON_DATA_MEMBER_HELPER(D), doc);
283283
}
284284

285285
template <class D>
286-
self& def_readwrite(char const* name, D const& d)
286+
self& def_readwrite(char const* name, D const& d, char const* doc=0)
287287
{
288-
return this->def_readwrite_impl(name, d BOOST_PYTHON_DATA_MEMBER_HELPER(D));
288+
return this->def_readwrite_impl(name, d BOOST_PYTHON_DATA_MEMBER_HELPER(D), doc);
289289
}
290290

291291
template <class D>
292-
self& def_readonly(char const* name, D& d)
292+
self& def_readonly(char const* name, D& d, char const* doc=0)
293293
{
294-
return this->def_readonly_impl(name, d BOOST_PYTHON_DATA_MEMBER_HELPER(D));
294+
return this->def_readonly_impl(name, d BOOST_PYTHON_DATA_MEMBER_HELPER(D), doc);
295295
}
296296

297297
template <class D>
298-
self& def_readwrite(char const* name, D& d)
298+
self& def_readwrite(char const* name, D& d, char const* doc=0)
299299
{
300-
return this->def_readwrite_impl(name, d BOOST_PYTHON_DATA_MEMBER_HELPER(D));
300+
return this->def_readwrite_impl(name, d BOOST_PYTHON_DATA_MEMBER_HELPER(D), doc);
301301
}
302302

303303
// Property creation
304304
template <class Get>
305-
self& add_property(char const* name, Get fget)
305+
self& add_property(char const* name, Get fget, char const* docstr = 0)
306306
{
307-
base::add_property(name, this->make_getter(fget));
307+
base::add_property(name, this->make_getter(fget), docstr);
308308
return *this;
309309
}
310310

311311
template <class Get, class Set>
312-
self& add_property(char const* name, Get fget, Set fset)
312+
self& add_property(char const* name, Get fget, Set fset, char const* docstr = 0)
313313
{
314-
base::add_property(name, this->make_getter(fget), this->make_setter(fset));
314+
base::add_property(
315+
name, this->make_getter(fget), this->make_setter(fset), docstr);
315316
return *this;
316317
}
317318

@@ -421,16 +422,16 @@ class class_ : public objects::class_base
421422

422423
template <class D, class B>
423424
self& def_readonly_impl(
424-
char const* name, D B::*pm_ BOOST_PYTHON_YES_DATA_MEMBER)
425+
char const* name, D B::*pm_ BOOST_PYTHON_YES_DATA_MEMBER, char const* doc)
425426
{
426-
return this->add_property(name, pm_);
427+
return this->add_property(name, pm_, doc);
427428
}
428429

429430
template <class D, class B>
430431
self& def_readwrite_impl(
431-
char const* name, D B::*pm_ BOOST_PYTHON_YES_DATA_MEMBER)
432+
char const* name, D B::*pm_ BOOST_PYTHON_YES_DATA_MEMBER, char const* doc)
432433
{
433-
return this->add_property(name, pm_, pm_);
434+
return this->add_property(name, pm_, pm_, doc);
434435
}
435436

436437
template <class D>

‎include/boost/python/object/class.hpp‎

Lines changed: 4 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -34,8 +34,10 @@ struct BOOST_PYTHON_DECL class_base : python::api::object
3434
void enable_pickling_(bool getstate_manages_dict);
3535

3636
protected:
37-
void add_property(char const* name, object const& fget);
38-
void add_property(char const* name, object const& fget, object const& fset);
37+
void add_property(
38+
char const* name, object const& fget, char const* docstr);
39+
void add_property(char const* name,
40+
object const& fget, object const& fset, char const* docstr);
3941

4042
void add_static_property(char const* name, object const& fget);
4143
void add_static_property(char const* name, object const& fget, object const& fset);

‎src/object/class.cpp‎

Lines changed: 6 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -535,20 +535,22 @@ namespace objects
535535
this->attr("__instance_size__") = instance_size;
536536
}
537537

538-
void class_base::add_property(char const* name, object const& fget)
538+
void class_base::add_property(
539+
char const* name, object const& fget, char const* docstr)
539540
{
540541
object property(
541542
(python::detail::new_reference)
542-
PyObject_CallFunction((PyObject*)&PyProperty_Type, "O", fget.ptr()));
543+
PyObject_CallFunction((PyObject*)&PyProperty_Type, "Osss", fget.ptr(), 0, 0, docstr));
543544

544545
this->setattr(name, property);
545546
}
546547

547-
void class_base::add_property(char const* name, object const& fget, object const& fset)
548+
void class_base::add_property(
549+
char const* name, object const& fget, object const& fset, char const* docstr)
548550
{
549551
object property(
550552
(python::detail::new_reference)
551-
PyObject_CallFunction((PyObject*)&PyProperty_Type, "OO", fget.ptr(), fset.ptr()));
553+
PyObject_CallFunction((PyObject*)&PyProperty_Type, "OOss", fget.ptr(), fset.ptr(), 0, docstr));
552554

553555
this->setattr(name, property);
554556
}

‎test/properties.cpp‎

Lines changed: 3 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -64,8 +64,11 @@ BOOST_PYTHON_MODULE(properties_ext)
6464
class_<X>("X", init<int>() )
6565
//defining read only property
6666
.add_property( "value_r", &X::get_value )
67+
.add_property( "value_r_ds", &X::get_value, "value_r_ds is read-only")
6768
//defining read \ write property
6869
.add_property( "value_rw", &X::get_value, &X::set_value )
70+
.add_property( "value_rw_ds", &X::get_value, &X::set_value,
71+
"value_rw_ds is read-write")
6972
//defining read \ write property using make_getter and make_setter
7073
.add_property( "value_direct",
7174
make_getter( &X::m_value, return_by_value_t() ),

‎test/properties.py‎

Lines changed: 5 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -79,6 +79,11 @@ class instance count from object:
7979
8080
>>> del x2
8181
>>> assert x1.instance_count == 1
82+
83+
>>> assert properties.X.value_r_ds.__doc__ == "value_r_ds is read-only"
84+
85+
>>> assert properties.X.value_rw_ds.__doc__ == "value_rw_ds is read-write"
86+
8287
"""
8388

8489
#import sys; sys.path.append(r'P:\Actimize4.0\smart_const\py_smart_const___Win32_Debug')

0 commit comments

Comments
 (0)