1[section boost/python/docstring_options.hpp]
2[section Introduction]
3Boost.Python supports user-defined docstrings with automatic appending of C++ signatures. These features are enabled by default. The class docstring_options is available to selectively suppress the user-defined docstrings, signatures, or both.
4[endsect]
5[section Class `docstring_options`]
6Controls the appearance of docstrings of wrapped functions and member functions for the life-time of the instance. The instances are noncopyable to eliminate the possibility of surprising side effects.
7
8``namespace boost { namespace python {
9
10  class docstring_options : boost::noncopyable
11  {
12  public:
13    docstring_options(bool show_all=true);
14    docstring_options(bool show_user_defined, bool show_signatures);
15    docstring_options(bool show_user_defined, bool show_py_signatures, bool show_cpp_signatures);
16    ~docstring_options();
17    void disable_user_defined();
18    void enable_user_defined();
19    void disable_signatures();
20    void enable_signatures();
21    void disable_py_signatures();
22    void enable_py_signatures();
23    void disable_cpp_signatures();
24    void enable_cpp_signatures();
25    void disable_all();
26    void enable_all();
27  };
28}}
29
30``
31[endsect]
32[section Class dostring_options constructors]
33``
34docstring_options(bool show_all=true);
35``
36[variablelist
37[[Effects][Constructs a docstring_options object which controls the appearance of function and member-function docstrings defined in the code that follows. If show_all is true, both the user-defined docstrings and the automatically generated Python and C++ signatures are shown. If show_all is false the `__doc__` attributes are `None`.]]
38]
39``
40docstring_options(bool show_user_defined, bool show_signatures);
41``
42[variablelist
43[[Effects][Constructs a `docstring_options` object which controls the appearance of function and member-function docstrings defined in the code that follows. Iff `show_user_defined` is `true`, the user-defined docstrings are shown. Iff `show_signatures` is `true`, Python and C++ signatures are automatically added. If both `show_user_defined` and `show_signatures` are `false`, the `__doc__` attributes are `None`.]]
44]
45``
46docstring_options(bool show_user_defined, bool show_py_signatures, bool show_cpp_signatures);
47``
48[variablelist
49[[Effects][Constructs a `docstring_options` object which controls the appearance of function and member-function docstrings defined in the code that follows. Iff `show_user_defined` is `true`, the user-defined docstrings are shown. Iff `show_py_signatures` is `true`, Python signatures are automatically added. Iff `show_cpp_signatures` is true, C++ signatures are automatically added. If all parameters are `false`, the `__doc__` attributes are `None`.]]
50]
51[endsect]
52[section Class docstring_options destructor]
53``~docstring_options();``
54[variablelist
55[[Effects][Restores the previous state of the docstring options. In particular, if `docstring_options` instances are in nested C++ scopes the settings effective in the enclosing scope are restored. If the last `docstring_options` instance goes out of scope the default "all on" settings are restored.]]]
56[endsect]
57[section Class `docstring_options` modifier functions]
58``
59void disable_user_defined();
60void enable_user_defined();
61void disable_signatures();
62void enable_signatures();
63void disable_py_signatures();
64void enable_py_signatures();
65void disable_cpp_signatures();
66void enable_cpp_signatures();
67void disable_all();
68void enable_all();
69``
70These member functions dynamically change the appearance of docstrings in the code that follows. The `*_user_defined()` and `*_signatures()` member functions are provided for fine-grained control. The `*_all()` member functions are convenient shortcuts to manipulate all settings simultaneously.
71[endsect]
72[section Example]
73[section Docstring options defined at compile time]
74``
75#include <boost/python/module.hpp>
76#include <boost/python/def.hpp>
77#include <boost/python/docstring_options.hpp>
78
79void foo() {}
80
81BOOST_PYTHON_MODULE(demo)
82{
83    using namespace boost::python;
84    docstring_options doc_options(DEMO_DOCSTRING_SHOW_ALL);
85    def("foo", foo, "foo doc");
86}
87``
88If compiled with `-DDEMO_DOCSTRING_SHOW_ALL=true`:
89``
90>>> import demo
91>>> print demo.foo.__doc__
92foo() -> None : foo doc
93C++ signature:
94    foo(void) -> void
95``
96If compiled with `-DDEMO_DOCSTRING_SHOW_ALL=false`:
97``
98>>> import demo
99>>> print demo.foo.__doc__
100None
101``
102[endsect]
103[section Selective suppressions]
104``
105#include <boost/python/module.hpp>
106#include <boost/python/def.hpp>
107#include <boost/python/args.hpp>
108#include <boost/python/docstring_options.hpp>
109
110int foo1(int i) { return i; }
111int foo2(long l) { return static_cast<int>(l); }
112int foo3(float f) { return static_cast<int>(f); }
113int foo4(double d) { return static_cast<int>(d); }
114
115BOOST_PYTHON_MODULE(demo)
116{
117    using namespace boost::python;
118    docstring_options doc_options;
119    def("foo1", foo1, arg("i"), "foo1 doc");
120    doc_options.disable_user_defined();
121    def("foo2", foo2, arg("l"), "foo2 doc");
122    doc_options.disable_signatures();
123    def("foo3", foo3, arg("f"), "foo3 doc");
124    doc_options.enable_user_defined();
125    def("foo4", foo4, arg("d"), "foo4 doc");
126    doc_options.enable_py_signatures();
127    def("foo5", foo4, arg("d"), "foo5 doc");
128    doc_options.disable_py_signatures();
129    doc_options.enable_cpp_signatures();
130    def("foo6", foo4, arg("d"), "foo6 doc");
131}
132``
133Python code:
134``
135>>> import demo
136>>> print demo.foo1.__doc__
137foo1( (int)i) -> int : foo1 doc
138C++ signature:
139    foo1(int i) -> int
140>>> print demo.foo2.__doc__
141foo2( (int)l) -> int :
142C++ signature:
143    foo2(long l) -> int
144>>> print demo.foo3.__doc__
145None
146>>> print demo.foo4.__doc__
147foo4 doc
148>>> print demo.foo5.__doc__
149foo5( (float)d) -> int : foo5 doc
150>>> print demo.foo6.__doc__
151foo6 doc
152C++ signature:
153    foo6(double d) -> int
154``
155[endsect]
156[section Wrapping from multiple C++ scopes]
157``
158#include <boost/python/module.hpp>
159#include <boost/python/def.hpp>
160#include <boost/python/args.hpp>
161#include <boost/python/docstring_options.hpp>
162
163int foo1(int i) { return i; }
164int foo2(long l) { return static_cast<int>(l); }
165
166int bar1(int i) { return i; }
167int bar2(long l) { return static_cast<int>(l); }
168
169namespace {
170
171    void wrap_foos()
172    {
173        using namespace boost::python;
174        // no docstring_options here
175        //   -> settings from outer C++ scope are in effect
176        def("foo1", foo1, arg("i"), "foo1 doc");
177        def("foo2", foo2, arg("l"), "foo2 doc");
178    }
179
180    void wrap_bars()
181    {
182        using namespace boost::python;
183        bool show_user_defined = true;
184        bool show_signatures = false;
185        docstring_options doc_options(show_user_defined, show_signatures);
186        def("bar1", bar1, arg("i"), "bar1 doc");
187        def("bar2", bar2, arg("l"), "bar2 doc");
188    }
189}
190
191BOOST_PYTHON_MODULE(demo)
192{
193    boost::python::docstring_options doc_options(false);
194    wrap_foos();
195    wrap_bars();
196}
197``
198Python code:
199``
200>>> import demo
201>>> print demo.foo1.__doc__
202None
203>>> print demo.foo2.__doc__
204None
205>>> print demo.bar1.__doc__
206bar1 doc
207>>> print demo.bar2.__doc__
208bar2 doc
209``
210
211[endsect]
212[endsect]
213[endsect]
214