Add docstrings

Author: ayllon

SEPythonModule/src/lib/SePyMain.cpp

@@ -57,48 +57,68 @@ BOOST_PYTHON_MODULE(_SEPythonModule) {
   np::initialize();
   py::object None;
 
+  // show_user_defined=true, show_py_signatures=true, show_cpp_signatures=false
+  py::docstring_options docstring_options(true, true, false);
+
   py::class_<Context, boost::noncopyable>(
-      "Context", py::init<py::dict, py::object>((py::arg("config"), py::arg("measurement_config") = py::object())))
-      .def("get_properties", &Context::get_properties)
-      .def("__enter__", &Context::enter)
-      .def("__exit__", &Context::exit);
+      "Context", "Required context for a sourcextractor++ run",
+      py::init<py::dict, py::object>(
+          (py::arg("config"), py::arg("measurement_config") = py::object()),
+          "config: Dictionary with key/value configuration (as sourcextractor .config file)\nmeasurement_config: An "
+          "instance of `sourcextractor.config.MeasurementConfig`"))
+      .def("get_properties", &Context::get_properties, "Get the available properties")
+      .def("__enter__", &Context::enter, "Activate the Context as default")
+      .def("__exit__", &Context::exit, "Clear the default context");
   py::register_ptr_to_python<std::shared_ptr<Context>>();
 
-  py::class_<DetachedSource>("DetachedSource")
-      .def("__repr__", &DetachedSource::repr)
+  py::class_<DetachedSource>("DetachedSource", "Source detached from the sourcextractor++ runtime")
+      .def("__repr__", &DetachedSource::repr, "Human-readable representation")
       .def("__getattr__", &DetachedSource::attribute)
       .def("__dir__", &DetachedSource::attributes)
       .def_pickle(PickleDetachedSource());
 
-  py::class_<AttachedSource, boost::noncopyable>("Source", py::no_init)
+  py::class_<AttachedSource, boost::noncopyable>("Source", "Source managed by the sourcextractor++ runtime",
+                                                 py::no_init)
       .def("__getattr__", &AttachedSource::attribute)
-      .def("detach", &AttachedSource::detach);
+      .def("detach", &AttachedSource::detach,
+           "Generate a `DetachedSource` containing its *current* computed properties");
   py::register_ptr_to_python<std::shared_ptr<AttachedSource>>();
 
-  py::class_<OwnedSource, py::bases<AttachedSource>, boost::noncopyable>("OwnedSource", py::no_init)
+  py::class_<OwnedSource, py::bases<AttachedSource>, boost::noncopyable>(
+      "OwnedSource", "Source managed by the sourcextractor++ runtime but owned by the callee", py::no_init)
       .def("__repr__", &OwnedSource::repr);
   py::register_ptr_to_python<std::shared_ptr<OwnedSource>>();
 
-  py::class_<EntangledSource, py::bases<AttachedSource>, boost::noncopyable>("EntangledSource", py::no_init)
+  py::class_<EntangledSource, py::bases<AttachedSource>, boost::noncopyable>(
+      "EntangledSource",
+      "Source managed by the sourcextractor++ runtime and tied to a Group. Their content is *undefined except when "
+      "iterating* a group",
+      py::no_init)
       .def("__repr__", &EntangledSource::repr);
 
   py::register_ptr_to_python<std::shared_ptr<EntangledSource>>();
 
   py::class_<SourceGroup::Iterator>("GroupIterator", py::no_init).def("__next__", &SourceGroup::Iterator::next);
 
-  py::class_<SourceGroup, boost::noncopyable>("Group", py::no_init)
+  py::class_<SourceGroup, boost::noncopyable>(
+      "Group", "Source group, managed by the sourcextractor++ runtime. Iterable.", py::no_init)
       .def("__repr__", &SourceGroup::repr)
       .def("__getattr__", &SourceGroup::attribute)
       .def("__len__", &SourceGroup::size)
       .def("__iter__", &SourceGroup::iter);
   py::register_ptr_to_python<std::shared_ptr<SourceGroup>>();
 
-  py::class_<ProcessSourcesEvent>("ProcessSourcesEvent", py::no_init).def("__repr__", &ProcessSourcesEvent::repr);
+  py::class_<ProcessSourcesEvent>(
+      "ProcessSourcesEvent",
+      "Signals processing events, as line flushes (i.e., for grouping when `segmentation-lutz-window-size` is enabled)",
+      py::no_init)
+      .def("__repr__", &ProcessSourcesEvent::repr);
 
   py::class_<SourceReceiverIfce, boost::noncopyable>("SourceReceiver", py::no_init);
   py::class_<GroupReceiverIfce, boost::noncopyable>("GroupReceiverIfce", py::no_init);
 
-  py::class_<Segmentation>("Segmentation", py::init<std::shared_ptr<Context>>((py::arg("context") = None)))
+  py::class_<Segmentation>("Segmentation", "First stage of the pipeline",
+                           py::init<std::shared_ptr<Context>>((py::arg("context") = None)))
       .def("__repr__", &Segmentation::repr)
       .def("set_next_stage", &Segmentation::setNextStage)
       .def("__call__", &Segmentation::call);
@@ -128,16 +148,18 @@ BOOST_PYTHON_MODULE(_SEPythonModule) {
       .def("__call__", &Measurement::call);
 
   py::class_<NumpyOutput, py::bases<GroupReceiverIfce>, boost::noncopyable>(
-      "NumpyOutput", py::init<std::shared_ptr<Context>>((py::arg("Context") = None)))
+      "NumpyOutput", "Generate a numpy structured array with the computed properties",
+      py::init<std::shared_ptr<Context>>((py::arg("Context") = None)))
       .def("__repr__", &NumpyOutput::repr)
       .def("__call__", &NumpyOutput::call)
-      .def("get", &NumpyOutput::getTable);
+      .def("get", &NumpyOutput::getTable, "Wait for the end of processing and return a numpy structured array");
 
   py::class_<FitsOutput, py::bases<GroupReceiverIfce>, boost::noncopyable>(
-      "FitsOutput", py::init<std::shared_ptr<Context>>((py::arg("Context") = None)))
+      "FitsOutput", "Generate a FITS catalog with the computed properties",
+      py::init<std::shared_ptr<Context>>((py::arg("Context") = None)))
       .def("__repr__", &FitsOutput::repr)
       .def("__call__", &FitsOutput::call)
-      .def("get", &FitsOutput::get);
+      .def("get", &FitsOutput::get, "Wait for the end of processing. Always returns None.");
 
 #if PY_MAJOR_VERSION >= 3
   PyObject* pyston = PyInit_pyston();