Name and describe arguments to constructors where ambiguous in `pyarb`. (#1678)

Fixes #1666

python/cells.cpp

@@ -267,7 +267,8 @@ void register_cells(pybind11::module& m) {
     pybind11::class_<arb::cv_policy> cv_policy(m, "cv_policy",
             "Describes the rules used to discretize (compartmentalise) a cable cell morphology.");
     cv_policy
-        .def(pybind11::init([](const std::string& s) { return arborio::parse_cv_policy_expression(s).unwrap(); }))
+        .def(pybind11::init([](const std::string& expression) { return arborio::parse_cv_policy_expression(expression).unwrap(); }),
+            "expression"_a, "A valid CV policy expression")
         .def_property_readonly("domain",
                                [](const arb::cv_policy& p) {return util::pprintf("{}", p.domain());},
                                "The domain on which the policy is applied.")
@@ -369,9 +370,8 @@ void register_cells(pybind11::module& m) {
             "A spike detector, generates a spike when voltage crosses a threshold. Can be used as source endpoint for an arbor.connection.");
     detector
         .def(pybind11::init(
-            [](double thresh) {
-                return arb::threshold_detector{thresh};
-            }), "threshold"_a)
+            [](double thresh) { return arb::threshold_detector{thresh}; }),
+            "threshold"_a, "Voltage threshold of spike detector [mV]")
         .def_readonly("threshold", &arb::threshold_detector::threshold, "Voltage threshold of spike detector [mV]")
         .def("__repr__", [](const arb::threshold_detector& d){
             return util::pprintf("<arbor.threshold_detector: threshold {} mV>", d.threshold);})
@@ -594,13 +594,15 @@ void register_cells(pybind11::module& m) {
         .def(pybind11::init(
             [](const arb::morphology& m, const label_dict_proxy& labels, const arb::decor& d) {
                 return arb::cable_cell(m, labels.dict, d);
-            }), "morphology"_a, "labels"_a, "decor"_a)
+            }),
+            "morphology"_a, "labels"_a, "decor"_a,
+            "Construct with a morphology, label dictionary and decor.")
         .def(pybind11::init(
             [](const arb::segment_tree& t, const label_dict_proxy& labels, const arb::decor& d) {
                 return arb::cable_cell(arb::morphology(t), labels.dict, d);
             }),
             "segment_tree"_a, "labels"_a, "decor"_a,
-            "Construct with a morphology derived from a segment tree.")
+            "Construct with a morphology derived from a segment tree, label dictionary and decor.")
         .def_property_readonly("num_branches",
             [](const arb::cable_cell& c) {return c.morphology().num_branches();},
             "The number of unbranched cable sections in the morphology.")

python/mechanism.cpp

@@ -204,7 +204,9 @@ void register_mechanisms(pybind11::module& m) {
 
     pybind11::class_<arb::mechanism_desc> mechanism_desc(m, "mechanism");
     mechanism_desc
-        .def(pybind11::init([](const char* n) {return arb::mechanism_desc{n};}))
+        .def(pybind11::init([](const char* name) {return arb::mechanism_desc{name};}),
+            "name"_a, "The name of the mechanism"
+        )
         // allow construction of a description with parameters provided in a dictionary:
         //      mech = arbor.mechanism('mech_name', {'param1': 1.2, 'param2': 3.14})
         .def(pybind11::init(

python/mpi.cpp

@@ -97,11 +97,14 @@ std::ostream& operator<<(std::ostream& o, const mpi_comm_shim& c) {
 
 void register_mpi(pybind11::module& m) {
     using namespace std::string_literals;
+    using namespace pybind11::literals;
 
     pybind11::class_<mpi_comm_shim> mpi_comm(m, "mpi_comm");
     mpi_comm
         .def(pybind11::init<>())
-        .def(pybind11::init([](pybind11::object o){return mpi_comm_shim(o);}))
+        .def(pybind11::init(
+            [](pybind11::object o){ return mpi_comm_shim(o); }),
+            "mpi_comm_obj"_a, "MPI communicator object.")
         .def("__str__",  util::to_string<mpi_comm_shim>)
         .def("__repr__", util::to_string<mpi_comm_shim>);