ceph/src/boost/libs/python/doc/reference/function_doc_signature.qbk

   1 [section boost/python/function_doc_signature.hpp]
   2 [section Introduction]
   3 Boost.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`]
   6 The class has only one public function which returns a list of strings documenting the overloads of a function.
   7 ``
   8 namespace 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
  29 using namespace boost::python;
  30
  31 tuple f(int x = 1, double y = 4.25, char const* z = "wow")
  32 {
  33     return make_tuple(x, y, z);
  34 }
  35
  36 BOOST_PYTHON_FUNCTION_OVERLOADS(f_overloads, f, 0, 3)
  37
  38
  39 struct 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
  47 BOOST_PYTHON_MEMBER_FUNCTION_OVERLOADS(X_f_overloads, X::f, 0, 3)
  48
  49 tuple raw_func(tuple args, dict kw)
  50 {
  51     return make_tuple(args, kw);
  52 }
  53
  54 BOOST_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 ``
  74 Python code: [python]
  75 ``
  76 >>> import args_ext
  77 >>> help(args_ext)
  78 Help on module args_ext:
  79
  80 NAME
  81     args_ext
  82
  83 FILE
  84     args_ext.pyd
  85
  86 CLASSES
  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      |
 112 FUNCTIONS
 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]