• Home
  • Line#
  • Scopes#
  • Navigate#
  • Raw
  • Download
1[section boost/python/function_doc_signature.hpp]
2[section Introduction]
3Boost.Python supports docstrings with automatic appending of Pythonic and C++ signatures. This feature is implemented by class `function_doc_signature_generator`. The class uses all of the overloads, supplied arg names and default values, as well as the user-defined docstrings, to generate documentation for a given function.
4[endsect]
5[section Class `function_doc_signature_generator`]
6The class has only one public function which returns a list of strings documenting the overloads of a function.
7``
8namespace boost { namespace python { namespace objects {
9
10    class function_doc_signature_generator
11    {
12      public:
13          static list function_doc_signatures(function const *f);
14    };
15
16}}}
17``
18[endsect]
19[section Example]
20``
21#include <boost/python/module.hpp>
22#include <boost/python/def.hpp>
23#include <boost/python/args.hpp>
24#include <boost/python/tuple.hpp>
25#include <boost/python/class.hpp>
26#include <boost/python/overloads.hpp>
27#include <boost/python/raw_function.hpp>
28
29using namespace boost::python;
30
31tuple f(int x = 1, double y = 4.25, char const* z = "wow")
32{
33    return make_tuple(x, y, z);
34}
35
36BOOST_PYTHON_FUNCTION_OVERLOADS(f_overloads, f, 0, 3)
37
38
39struct X
40{
41    tuple f(int x = 1, double y = 4.25, char const* z = "wow")
42    {
43        return make_tuple(x, y, z);
44    }
45};
46
47BOOST_PYTHON_MEMBER_FUNCTION_OVERLOADS(X_f_overloads, X::f, 0, 3)
48
49tuple raw_func(tuple args, dict kw)
50{
51    return make_tuple(args, kw);
52}
53
54BOOST_PYTHON_MODULE(args_ext)
55{
56    def("f", f, (arg("x")=1, arg("y")=4.25, arg("z")="wow")
57        , "This is f's docstring"
58        );
59
60    def("raw", raw_function(raw_func));
61
62    def("f1", f, f_overloads("f1's docstring", args("x", "y", "z")));
63
64
65    class_<X>("X", "This is X's docstring", init<>(args("self")))
66        .def("f", &X::f
67             , "This is X.f's docstring"
68             , args("self","x", "y", "z"))
69
70        ;
71
72}
73``
74Python code: [python]
75``
76>>> import args_ext
77>>> help(args_ext)
78Help on module args_ext:
79
80NAME
81    args_ext
82
83FILE
84    args_ext.pyd
85
86CLASSES
87    Boost.Python.instance(__builtin__.object)
88        X
89
90    class X(Boost.Python.instance)
91     |  This is X's docstring
92     |
93     |  Method resolution order:
94     |      X
95     |      Boost.Python.instance
96     |      __builtin__.object
97     |
98     |  Methods defined here:
99     |
100     |  __init__(...)
101     |      __init__( (object)self) -> None :
102     |       C++ signature:
103     |           void __init__(struct _object *)
104     |
105     |  f(...)
106     |      f( (X)self, (int)x, (float)y, (str)z) -> tuple : This is X.f's docstring
107     |      C++ signature:
108     |          class boost::python::tuple f(struct X {lvalue},int,double,char const *)
109     |
110     |    .................
111     |
112FUNCTIONS
113    f(...)
114        f([ (int)x=1 [, (float)y=4.25 [, (str)z='wow']]]) -> tuple : This is f's docstring
115        C++ signature:
116            class boost::python::tuple f([ int=1 [,double=4.25 [,char const *='wow']]])
117
118    f1(...)
119        f1([ (int)x [, (float)y [, (str)z]]]) -> tuple : f1's docstring
120        C++ signature:
121            class boost::python::tuple f1([ int [,double [,char const *]]])
122
123    raw(...)
124        object raw(tuple args, dict kwds) :
125        C++ signature:
126            object raw(tuple args, dict kwds)
127``
128[endsect]
129[endsect]
130