move docs for _osmium module to pyi files

This gives us better control over the output and is more easy to
maintain.

lib/file_iterator.cc

@@ -139,17 +139,15 @@ namespace pyosmium {
 
 void init_osm_file_iterator(py::module &m)
 {
-    py::class_<OsmFileIterator>(m, "OsmFileIterator",
-        "Iterator interface for reading an OSM file.")
+    py::class_<OsmFileIterator>(m, "OsmFileIterator")
         .def(py::init<osmium::io::Reader *, py::args>(),
              py::keep_alive<0, 1>())
         .def("set_filtered_handler", &OsmFileIterator::set_filtered_handler,
              py::keep_alive<0, 1>())
         .def("set_filtered_handler", &OsmFileIterator::set_filtered_python_handler,
              py::keep_alive<0, 1>())
         .def("__iter__", [](py::object const &self) { return self; })
-        .def("__next__", &OsmFileIterator::next,
-             "Get the next OSM object from the file or raise a StopIteration.")
+        .def("__next__", &OsmFileIterator::next)
         ;
 }
 

lib/merge_input_reader.cc

@@ -165,30 +165,16 @@ namespace pyosmium {
 
 void init_merge_input_reader(py::module &m)
 {
-    py::class_<MergeInputReader>(m, "MergeInputReader",
-        "Collects data from multiple input files, sorts and optionally "
-        "deduplicates the data before applying it to a handler.")
+    py::class_<MergeInputReader>(m, "MergeInputReader")
         .def(py::init<>())
         .def("_apply_internal", &MergeInputReader::apply_internal,
              py::arg("simplify")=true)
         .def("apply_to_reader", &MergeInputReader::apply_to_reader,
-             py::arg("reader"), py::arg("writer"), py::arg("with_history")=false,
-             "Apply the collected data to data from the given `reader` and write "
-             "the result to `writer`. This function can be used to merge the diff "
-             "data together with other OSM data (for example when updating a "
-             "planet file. If `with_history` is true, then the collected data will "
-             "be applied verbatim without removing duplicates. This is important "
-             "when using OSM history files as input.")
+             py::arg("reader"), py::arg("writer"), py::arg("with_history")=false)
         .def("add_file", &MergeInputReader::add_file,
-             py::arg("file"),
-             "Add data from a file to the internal cache. The file type will be "
-             "determined from the file extension.")
+             py::arg("file"))
         .def("add_buffer", &MergeInputReader::add_buffer,
-             py::arg("buffer"), py::arg("format"),
-             "Add data from a byte buffer. The format of the input data must "
-             "be given in the `format` argument as a string. The data will be "
-             "copied into internal buffers, so that the input buffer can be "
-             "safely discarded after the function has been called.")
+             py::arg("buffer"), py::arg("format"))
     ;
 };
 

lib/node_location_handler.cc

@@ -67,9 +67,7 @@ void init_node_location_handler(py::module &m)
         .def("ignore_errors", &NodeLocationsForWays::ignore_errors)
         .def_property("apply_nodes_to_ways",
                      &NodeLocationsForWays::get_apply_nodes_to_ways,
-                     &NodeLocationsForWays::set_apply_nodes_to_ways,
-                     "When set to false, locations are only collected "
-                     "and not automatically applied to way nodes.")
+                     &NodeLocationsForWays::set_apply_nodes_to_ways)
     ;
 
 }

lib/osmium.cc

@@ -82,48 +82,38 @@ PYBIND11_MODULE(_osmium, m) {
     });
 
     m.def("apply", &pyosmium::apply,
-          py::arg("reader"), py::arg("handler"),
-          "Apply a single handler.");
+          py::arg("reader"), py::arg("handler"));
     m.def("apply", [](osmium::io::Reader &rd, py::args args)
                      {
                          pyosmium::HandlerChain handler{args};
                          pyosmium::apply(rd, handler);
                      },
-          py::arg("reader"),
-          "Apply a chain of handlers.");
+          py::arg("reader"));
     m.def("apply", [](std::string fn, pyosmium::BaseHandler &h)
                    {
                        osmium::io::Reader rd{fn};
                        pyosmium::apply(rd, h);
                    },
-          py::arg("filename"), py::arg("handler"),
-          "Apply a single handler.");
+          py::arg("filename"), py::arg("handler"));
     m.def("apply", [](std::string fn, py::args args)
                      {
                          pyosmium::HandlerChain handler{args};
                          osmium::io::Reader rd{fn};
                          pyosmium::apply(rd, handler);
                      },
-          py::arg("filename"),
-          "Apply a chain of handlers.");
+          py::arg("filename"));
 
-    py::class_<pyosmium::BaseHandler>(m, "BaseHandler",
-             "Base class for all handlers in pyosmium. Any class inheriting "
-             "from this class can be used in functions that require a "
-             "handler-like object.");
+    py::class_<pyosmium::BaseHandler>(m, "BaseHandler");
     py::class_<pyosmium::BaseFilter, pyosmium::BaseHandler>(m, "BaseFilter")
         .def("enable_for", &pyosmium::BaseFilter::enable_for,
-             py::arg("entities"),
-             "Set the OSM types this filter should be used for.")
+             py::arg("entities"))
     ;
 
-    py::class_<pyosmium::BufferIterator>(m, "BufferIterator",
-    "Iterator interface for reading from a queue of buffers.")
+    py::class_<pyosmium::BufferIterator>(m, "BufferIterator")
     .def(py::init<py::args>())
     .def("__bool__", [](pyosmium::BufferIterator const &it) { return !it.empty(); })
     .def("__iter__", [](py::object const &self) { return self; })
-    .def("__next__", &pyosmium::BufferIterator::next,
-         "Get the next OSM object from the buffer or raise an StopIteration.")
+    .def("__next__", &pyosmium::BufferIterator::next)
     ;
 
     pyosmium::init_merge_input_reader(m);

lib/simple_writer.cc

@@ -338,36 +338,15 @@ namespace pyosmium {
 
 void init_simple_writer(pybind11::module &m)
 {
-    py::class_<SimpleWriter, BaseHandler>(m, "SimpleWriter",
-        "The most generic class to write osmium objects into a file. The writer "
-        "takes a file name as its mandatory parameter. The file must not yet "
-        "exist. The file type to output is determined from the file extension. "
-        "The second (optional) parameter is the buffer size. osmium caches the "
-        "output data in an internal memory buffer before writing it on disk. This "
-        "parameter allows changing the default buffer size of 4MB. Larger buffers "
-        "are normally better but you should be aware that there are normally multiple "
-        "buffers in use during the write process.\n\n"
-        "The writer will not overwrite existing files by default. Set `overwrite` "
-        "to True to allow overwriting.\n\n"
-        "The SimpleWriter can also functions as a handler and will write out "
-        "all node, ways and relations, it receives.")
+    py::class_<SimpleWriter, BaseHandler>(m, "SimpleWriter")
         .def(py::init<const char*, unsigned long, osmium::io::Header const *, bool, const std::string&>(),
              py::arg("filename"), py::arg("bufsz") = 4096*1024,
              py::arg("header") = nullptr,
              py::arg("overwrite") = false,
              py::arg("filetype") = "")
-        .def("add_node", &SimpleWriter::add_node, py::arg("node"),
-             "Add a new node to the file. The node may be an ``osmium.osm.Node`` object, "
-             "an ``osmium.osm.mutable.Node`` object or any other Python object that "
-             "implements the same attributes.")
-        .def("add_way", &SimpleWriter::add_way, py::arg("way"),
-             "Add a new way to the file. The way may be an ``osmium.osm.Way`` object, "
-             "an ``osmium.osm.mutable.Way`` object or any other Python object that "
-             "implements the same attributes.")
-        .def("add_relation", &SimpleWriter::add_relation, py::arg("relation"),
-             "Add a new relation to the file. The relation may be an "
-             "``osmium.osm.Relation`` object, an ``osmium.osm.mutable.Relation`` "
-             "object or any other Python object that implements the same attributes.")
+        .def("add_node", &SimpleWriter::add_node, py::arg("node"))
+        .def("add_way", &SimpleWriter::add_way, py::arg("way"))
+        .def("add_relation", &SimpleWriter::add_relation, py::arg("relation"))
         .def("add", [](SimpleWriter &self, py::object const &o) {
                            if (py::isinstance<pyosmium::COSMNode>(o) || py::hasattr(o, "location")) {
                                self.add_node(o);
@@ -378,14 +357,8 @@ void init_simple_writer(pybind11::module &m)
                            } else {
                                throw py::type_error("Need node, way or relation object.");
                            }
-                    },
-             "Add a new object to the file. The function will try to determine "
-             "the kind of object automatically.")
-        .def("close", &SimpleWriter::close,
-             "Flush the remaining buffers and close the writer. While it is not "
-             "strictly necessary to call this function explicitly, it is still "
-             "strongly recommended to close the writer as soon as possible, so "
-             "that the buffer memory can be freed.")
+                    })
+        .def("close", &SimpleWriter::close)
         .def("__enter__", [](py::object const &self) { return self; })
         .def("__exit__", [](SimpleWriter &self, py::args args) { self.close(); })
     ;