Planet
navi homePPSaboutscreenshotsdownloaddevelopmentforum

source: downloads/boost_1_34_1/libs/python/doc/v2/docstring_options.html @ 45

Last change on this file since 45 was 29, checked in by landauf, 17 years ago

updated boost from 1_33_1 to 1_34_1
File size: 9.7 KB
Line 
1<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN">
2
3<!-- Copyright David Abrahams 2006. Distributed under the Boost -->
4<!-- Software License, Version 1.0. (See accompanying -->
5<!-- file LICENSE_1_0.txt or copy at http://www.boost.org/LICENSE_1_0.txt) -->
6<html>
7<head>
8  <meta name="generator" content=
9  "HTML Tidy for Linux/x86 (vers 1st September 2004), see www.w3.org">
10  <meta http-equiv="Content-Type" content=
11  "text/html; charset=us-ascii">
12  <link rel="stylesheet" type="text/css" href="../boost.css">
13
14  <title>Boost.Python -
15  &lt;boost/python/docstring_options.hpp&gt;</title>
16</head>
17
18<body>
19  <table border="0" cellpadding="7" cellspacing="0" width="100%"
20  summary="header">
21    <tr>
22      <td valign="top" width="300">
23        <h3><a href="../../../../index.htm"><img height="86" width=
24        "277" alt="C++ Boost" src="../../../../boost.png" border=
25        "0"></a></h3>
26      </td>
27
28      <td valign="top">
29        <h1 align="center"><a href=
30        "../index.html">Boost.Python</a></h1>
31
32        <h2 align="center">Header
33        &lt;boost/python/docstring_options.hpp&gt;</h2>
34      </td>
35    </tr>
36  </table>
37  <hr>
38
39  <h2>Contents</h2>
40
41  <dl class="page-index">
42    <dt><a href="#introduction">Introduction</a></dt>
43
44    <dt><a href="#classes">Classes</a></dt>
45
46    <dd>
47      <dl class="page-index">
48        <dt><a href="#docstring_options-spec">Class
49        <code>docstring_options</code></a></dt>
50
51        <dd>
52          <dl class="page-index">
53            <dt><a href="#docstring_options-spec-synopsis">Class
54            <code>docstring_options</code> synopsis</a></dt>
55
56            <dt><a href="#docstring_options-spec-ctors">Class
57            <code>docstring_options</code> constructors</a></dt>
58
59            <dt><a href="#docstring_options-spec-dtors">Class
60            <code>docstring_options</code> destructors</a></dt>
61
62            <dt><a href="#docstring_options-spec-modifiers">Class
63            <code>docstring_options</code> modifiers</a></dt>
64          </dl>
65        </dd>
66      </dl>
67    </dd>
68
69    <dt><a href="#examples">Examples</a></dt>
70  </dl>
71  <hr>
72
73  <h2><a name="introduction" id=
74  "introduction"></a>Introduction</h2>
75
76  <p>Boost.Python supports user-defined docstrings with automatic
77  appending of C++ signatures. These features are enabled by
78  default. The <code>class docstring_options</code> is available to
79  selectively suppress the user-defined docstrings, signatures, or
80  both.</p>
81
82  <h2><a name="classes" id="classes"></a>Classes</h2>
83
84  <h3><a name="docstring_options-spec" id=
85  "docstring_options-spec"></a>Class
86  <code>docstring_options</code></h3>
87
88  <p>Controls the appearance of docstrings of wrapped functions and
89  member functions for the life-time of the instance. The instances
90  are noncopyable to eliminate the possibility of surprising side
91  effects.</p>
92
93  <h4><a name="docstring_options-spec-synopsis" id=
94  "docstring_options-spec-synopsis"></a>Class
95  <code>docstring_options</code> synopsis</h4>
96  <pre>
97namespace boost { namespace python {
98
99    class docstring_options : boost::noncopyable
100    {
101      public:
102          docstring_options(bool show_all=true);
103
104          docstring_options(bool show_user_defined, bool show_signatures);
105
106          ~docstring_options();
107
108          void
109          disable_user_defined();
110
111          void
112          enable_user_defined();
113
114          void
115          disable_signatures();
116
117          void
118          enable_signatures();
119
120          void
121          disable_all();
122
123          void
124          enable_all();
125    };
126
127}}
128</pre>
129
130  <h4><a name="docstring_options-spec-ctors" id=
131  "docstring_options-spec-ctors"></a>Class
132  <code>docstring_options</code> constructors</h4>
133  <pre>
134docstring_options(bool show_all=true);
135</pre>
136
137  <dl class="function-semantics">
138    <dt><b>Effects:</b> Constructs a <code>docstring_options</code>
139    object which controls the appearance of function and
140    member-function docstrings defined in the code that follows. If
141    <code>show_all</code> is <code>true</code>, both the
142    user-defined docstrings and the automatically generated C++
143    signatures are shown. If <code>show_all</code> is
144    <code>false</code> the <code>__doc__</code> attributes are
145    <code>None</code>.</dt>
146  </dl>
147  <pre>
148docstring_options(bool show_user_defined, bool show_signatures);
149</pre>
150
151  <dl class="function-semantics">
152    <dt><b>Effects:</b> Constructs a <code>docstring_options</code>
153    object which controls the appearance of function and
154    member-function docstrings defined in the code that follows.
155    Iff <code>show_user_defined</code> is <code>true</code>, the
156    user-defined docstrings are shown. Iff
157    <code>show_signatures</code> is <code>true</code>, C++
158    signatures are automatically added. If both
159    <code>show_user_defined</code> and <code>show_signatures</code>
160    are <code>false</code>, the <code>__doc__</code> attributes are
161    <code>None</code>.</dt>
162  </dl>
163
164  <h4><a name="docstring_options-spec-dtors" id=
165  "docstring_options-spec-dtors"></a>Class
166  <code>docstring_options</code> destructors</h4>
167  <pre>
168~docstring_options();
169</pre>
170
171  <dl class="function-semantics">
172    <dt><b>Effects:</b> Restores the previous state of the
173    docstring options. In particular, if
174    <code>docstring_options</code> instances are in nested C++
175    scopes the settings effective in the enclosing scope are
176    restored. If the last <code>docstring_options</code> instance
177    goes out of scope the default "all on" settings are
178    restored.</dt>
179  </dl>
180
181  <h4><a name="docstring_options-spec-modifiers" id=
182  "docstring_options-spec-modifiers"></a>Class
183  <code>docstring_options</code> modifier functions</h4>
184  <pre>
185void disable_user_defined();
186void enable_user_defined();
187void disable_signatures();
188void enable_signatures();
189void disable_all();
190void enable_all();
191</pre>
192
193  <dl class="function-semantics">
194    <dt>These member functions dynamically change the appearance of
195    docstrings in the code that follows. The
196    <code>*_user_defined()</code> and <code>*_signatures()</code>
197    member functions are provided for fine-grained control. The
198    <code>*_all()</code> member functions are convenient shortcuts
199    to manipulate both settings simultaneously.</dt>
200  </dl>
201
202  <h2><a name="examples" id="examples"></a>Examples</h2>
203
204  <h4>Docstring options defined at compile time</h4>
205  <pre>
206#include &lt;boost/python/module.hpp&gt;
207#include &lt;boost/python/def.hpp&gt;
208#include &lt;boost/python/docstring_options.hpp&gt;
209
210void foo() {}
211
212BOOST_PYTHON_MODULE(demo)
213{
214    using namespace boost::python;
215    docstring_options doc_options(DEMO_DOCSTRING_SHOW_ALL);
216    def("foo", foo, "foo doc");
217}
218</pre>If compiled with <code>-DDEMO_DOCSTRING_SHOW_ALL=true</code>:
219  <pre>
220&gt;&gt;&gt; import demo
221&gt;&gt;&gt; print demo.foo.__doc__
222foo doc
223C++ signature:
224    foo(void) -&gt; void
225</pre>If compiled with
226<code>-DDEMO_DOCSTRING_SHOW_ALL=false</code>:
227  <pre>
228&gt;&gt;&gt; import demo
229&gt;&gt;&gt; print demo.foo.__doc__
230None
231</pre>
232
233  <h4>Selective suppressions</h4>
234  <pre>
235#include &lt;boost/python/module.hpp&gt;
236#include &lt;boost/python/def.hpp&gt;
237#include &lt;boost/python/args.hpp&gt;
238#include &lt;boost/python/docstring_options.hpp&gt;
239
240int foo1(int i) { return i; }
241int foo2(long l) { return static_cast&lt;int&gt;(l); }
242int foo3(float f) { return static_cast&lt;int&gt;(f); }
243int foo4(double d) { return static_cast&lt;int&gt;(d); }
244
245BOOST_PYTHON_MODULE(demo)
246{
247    using namespace boost::python;
248    docstring_options doc_options;
249    def("foo1", foo1, arg("i"), "foo1 doc");
250    doc_options.disable_user_defined();
251    def("foo2", foo2, arg("l"), "foo2 doc");
252    doc_options.disable_signatures();
253    def("foo3", foo3, arg("f"), "foo3 doc");
254    doc_options.enable_user_defined();
255    def("foo4", foo4, arg("d"), "foo4 doc");
256}
257</pre>Python code:
258  <pre>
259&gt;&gt;&gt; import demo
260&gt;&gt;&gt; print demo.foo1.__doc__
261foo1 doc
262C++ signature:
263    foo1(int i) -&gt; int
264&gt;&gt;&gt; print demo.foo2.__doc__
265C++ signature:
266    foo2(long l) -&gt; int
267&gt;&gt;&gt; print demo.foo3.__doc__
268None
269&gt;&gt;&gt; print demo.foo4.__doc__
270foo4 doc
271</pre>
272
273  <h4>Wrapping from multiple C++ scopes</h4>
274  <pre>
275#include &lt;boost/python/module.hpp&gt;
276#include &lt;boost/python/def.hpp&gt;
277#include &lt;boost/python/args.hpp&gt;
278#include &lt;boost/python/docstring_options.hpp&gt;
279
280int foo1(int i) { return i; }
281int foo2(long l) { return static_cast&lt;int&gt;(l); }
282
283int bar1(int i) { return i; }
284int bar2(long l) { return static_cast&lt;int&gt;(l); }
285
286namespace {
287
288    void wrap_foos()
289    {
290        using namespace boost::python;
291        // no docstring_options here
292        //   -&gt; settings from outer C++ scope are in effect
293        def("foo1", foo1, arg("i"), "foo1 doc");
294        def("foo2", foo2, arg("l"), "foo2 doc");
295    }
296
297    void wrap_bars()
298    {
299        using namespace boost::python;
300        bool show_user_defined = true;
301        bool show_signatures = false;
302        docstring_options doc_options(show_user_defined, show_signatures);
303        def("bar1", bar1, arg("i"), "bar1 doc");
304        def("bar2", bar2, arg("l"), "bar2 doc");
305    }
306}
307
308BOOST_PYTHON_MODULE(demo)
309{
310    boost::python::docstring_options doc_options(false);
311    wrap_foos();
312    wrap_bars();
313}
314</pre>Python code:
315  <pre>
316&gt;&gt;&gt; import demo
317&gt;&gt;&gt; print demo.foo1.__doc__
318None
319&gt;&gt;&gt; print demo.foo2.__doc__
320None
321&gt;&gt;&gt; print demo.bar1.__doc__
322bar1 doc
323&gt;&gt;&gt; print demo.bar2.__doc__
324bar2 doc
325</pre>
326
327  <h4>See also: <code>boost/libs/python/test/docstring.cpp</code>
328  and <code>docstring.py</code></h4>
329
330  <p>Revised
331  <!--webbot bot="Timestamp" S-Type="EDITED" S-Format="%d %B, %Y" startspan -->
332   16 January, 2006
333  <!--webbot bot="Timestamp" endspan i-checksum="39359" --></p>
334
335  <p><i>&copy; Copyright <a href=
336  "../../../../people/ralf_w_grosse_kunstleve.htm">Ralf W.
337  Grosse-Kunstleve</a> 2006.</i></p>
338</body>
339</html>
Note: See TracBrowser for help on using the repository browser.