###

# Boost.Python

## Header <boost/python/docstring_options.hpp>

## Contents

Introduction
Classes
  Class `docstring_options`
    Class `docstring_options` synopsis
    Class `docstring_options` constructors
    Class `docstring_options` destructors
    Class `docstring_options` modifiers
Examples

## Introduction

Boost.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.

## Classes

### Class `docstring_options`

Controls 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.

#### Class `docstring_options` synopsis

    namespace boost { namespace python {

        class docstring_options : boost::noncopyable
        {
          public:
              docstring_options(bool show_all=true);

              docstring_options(bool show_user_defined, bool show_signatures);

              ~docstring_options();

              void
              disable_user_defined();

              void
              enable_user_defined();

              void
              disable_signatures();

              void
              enable_signatures();

              void
              disable_all();

              void
              enable_all();
        };

    }}

#### Class `docstring_options` constructors

    docstring_options(bool show_all=true);

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 C++ signatures are shown. If `show_all` is `false` the `__doc__` attributes are `None`.

    docstring_options(bool show_user_defined, bool show_signatures);

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`, C++ signatures are automatically added. If both `show_user_defined` and `show_signatures` are `false`, the `__doc__` attributes are `None`.

#### Class `docstring_options` destructors

    ~docstring_options();

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.

#### Class `docstring_options` modifier functions

    void disable_user_defined();
    void enable_user_defined();
    void disable_signatures();
    void enable_signatures();
    void disable_all();
    void enable_all();

These 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 both settings simultaneously.

## Examples

#### Docstring options defined at compile time

    #include <boost/python/module.hpp>
    #include <boost/python/def.hpp>
    #include <boost/python/docstring_options.hpp>

    void foo() {}

    BOOST_PYTHON_MODULE(demo)
    {
        using namespace boost::python;
        docstring_options doc_options(DEMO_DOCSTRING_SHOW_ALL);
        def("foo", foo, "foo doc");
    }

If compiled with `-DDEMO_DOCSTRING_SHOW_ALL=true`:

    >>> import demo
    >>> print demo.foo.__doc__
    foo doc
    C++ signature:
        foo(void) -> void

If compiled with `-DDEMO_DOCSTRING_SHOW_ALL=false`:

    >>> import demo
    >>> print demo.foo.__doc__
    None

#### Selective suppressions

    #include <boost/python/module.hpp>
    #include <boost/python/def.hpp>
    #include <boost/python/args.hpp>
    #include <boost/python/docstring_options.hpp>

    int foo1(int i) { return i; }
    int foo2(long l) { return static_cast<int>(l); }
    int foo3(float f) { return static_cast<int>(f); }
    int foo4(double d) { return static_cast<int>(d); }

    BOOST_PYTHON_MODULE(demo)
    {
        using namespace boost::python;
        docstring_options doc_options;
        def("foo1", foo1, arg("i"), "foo1 doc");
        doc_options.disable_user_defined();
        def("foo2", foo2, arg("l"), "foo2 doc");
        doc_options.disable_signatures();
        def("foo3", foo3, arg("f"), "foo3 doc");
        doc_options.enable_user_defined();
        def("foo4", foo4, arg("d"), "foo4 doc");
    }

Python code:

    >>> import demo
    >>> print demo.foo1.__doc__
    foo1 doc
    C++ signature:
        foo1(int i) -> int
    >>> print demo.foo2.__doc__
    C++ signature:
        foo2(long l) -> int
    >>> print demo.foo3.__doc__
    None
    >>> print demo.foo4.__doc__
    foo4 doc

#### Wrapping from multiple C++ scopes

    #include <boost/python/module.hpp>
    #include <boost/python/def.hpp>
    #include <boost/python/args.hpp>
    #include <boost/python/docstring_options.hpp>

    int foo1(int i) { return i; }
    int foo2(long l) { return static_cast<int>(l); }

    int bar1(int i) { return i; }
    int bar2(long l) { return static_cast<int>(l); }

    namespace {

        void wrap_foos()
        {
            using namespace boost::python;
            // no docstring_options here
            //   -> settings from outer C++ scope are in effect
            def("foo1", foo1, arg("i"), "foo1 doc");
            def("foo2", foo2, arg("l"), "foo2 doc");
        }

        void wrap_bars()
        {
            using namespace boost::python;
            bool show_user_defined = true;
            bool show_signatures = false;
            docstring_options doc_options(show_user_defined, show_signatures);
            def("bar1", bar1, arg("i"), "bar1 doc");
            def("bar2", bar2, arg("l"), "bar2 doc");
        }
    }

    BOOST_PYTHON_MODULE(demo)
    {
        boost::python::docstring_options doc_options(false);
        wrap_foos();
        wrap_bars();
    }

Python code:

    >>> import demo
    >>> print demo.foo1.__doc__
    None
    >>> print demo.foo2.__doc__
    None
    >>> print demo.bar1.__doc__
    bar1 doc
    >>> print demo.bar2.__doc__
    bar2 doc

#### See also: `boost/libs/python/test/docstring.cpp` and `docstring.py`

Revised 16 January, 2006

© Copyright Ralf W. Grosse-Kunstleve 2006.