From 007e280480bc3e0f3cf79cfccf3793ef3b0234f8 Mon Sep 17 00:00:00 2001
From: Hans Dembinski <hans.dembinski@icecube.wisc.edu>
Date: Thu, 14 Apr 2016 23:37:56 -0400
Subject: [PATCH] more docstrings

---
 src/python/basic_histogram.cpp | 17 +++++++++++++----
 src/python/histogram.cpp       | 32 ++++++++++++++++++++++++++------
 2 files changed, 39 insertions(+), 10 deletions(-)

diff --git a/src/python/basic_histogram.cpp b/src/python/basic_histogram.cpp
index 56da56c5..82fe2cb8 100644
--- a/src/python/basic_histogram.cpp
+++ b/src/python/basic_histogram.cpp
@@ -271,6 +271,7 @@ basic_histogram_axis(const basic_histogram& self, unsigned i)
 void register_basic_histogram() {
   using namespace python;
   using python::arg;
+  docstring_options dopt(true, true, false);
 
   // used to pass arguments from raw python init to specialized C++ constructors
   class_<std::vector<double> >("vector_double", no_init);
@@ -314,10 +315,18 @@ void register_basic_histogram() {
     ;
 
   class_<basic_histogram>("basic_histogram", no_init)
-    .add_property("dim", &basic_histogram::dim)
-    .def("bins", &basic_histogram::bins)
-    .def("shape", &basic_histogram::shape)
-    .def("axis", basic_histogram_axis)
+    .add_property("dim", &basic_histogram::dim,
+                  ":return: dimensions of the histogram")
+    .def("shape", &basic_histogram::shape,
+         ":param int i: index of the axis\n"
+         ":return: number of count fields for axis i\n"
+         "  (bins + 2 if underflow and overflow"
+         " bins are enabled, otherwise equal to bins",
+         args("self", "i"))
+    .def("axis", basic_histogram_axis,
+         ":param int i: index of the axis\n"
+         ":return: axis object for axis i",
+         args("self", "i"))
     ;
 }
 
diff --git a/src/python/histogram.cpp b/src/python/histogram.cpp
index bb3f0bfa..d4dc709b 100644
--- a/src/python/histogram.cpp
+++ b/src/python/histogram.cpp
@@ -220,20 +220,40 @@ public:
 void register_histogram()
 {
     using namespace python;
+    docstring_options dopt(true, true, false);
 
     class_<
       histogram, bases<basic_histogram>,
       shared_ptr<histogram>
-    >("histogram", no_init)
-        .def("__init__", raw_function(histogram_init))
+    >("histogram",
+      "N-dimensional histogram for real-valued data.",
+      no_init)
+        .def("__init__", raw_function(histogram_init),
+             ":param axis args: axis objects"
+             "\nPass one or more axis objects to define"
+             "\nthe dimensions of the histogram.")
         // shadowed C++ ctors
         .def(init<const basic_histogram::axes_type&>())
-        .add_property("__array_interface__", &histogram_access::histogram_array_interface)
-        .def("fill", raw_function(histogram_fill))
+        .add_property("__array_interface__",
+                      &histogram_access::histogram_array_interface)
+        .def("fill", raw_function(histogram_fill),
+             "Pass a sequence of values with a length n is"
+             "\nequal to the dimensions of the histogram,"
+             "\nand optionally a weight w for this fill"
+             "\n(*int* or *float*)."
+             "\n"
+             "\nIf Numpy support is enabled, values my also"
+             "\nbe a 2d-array of shape (m, n), where m is"
+             "\nthe number of tuples, and optionally"
+             "\nanother a second 1d-array w of shape (n,).")
         .add_property("depth", &histogram::depth)
         .add_property("sum", &histogram::sum)
-        .def("value", raw_function(histogram_value))
-        .def("variance", raw_function(histogram_variance))
+        .def("value", raw_function(histogram_value),
+             ":param int args: indices of the bin"
+             "\n:return: value for the bin")
+        .def("variance", raw_function(histogram_variance),
+             ":param int args: indices of the bin"
+             "\n:return: variance estimate for the bin")
         .def(self == self)
         .def(self += self)
         .def(self + self)