From 8fa97cc60ebe04bba99c2f16465772808f533dc8 Mon Sep 17 00:00:00 2001
From: Daniel Schadt <kingdread@gmx.de>
Date: Mon, 28 Jul 2025 22:34:22 +0200
Subject: add some docstrings

They are not really visible but useful documentation anyway.
---
 hittekaart-py/src/lib.rs | 24 ++++++++++++++++++++++++
 1 file changed, 24 insertions(+)

diff --git a/hittekaart-py/src/lib.rs b/hittekaart-py/src/lib.rs
index 2ad0e56..782f9e7 100644
--- a/hittekaart-py/src/lib.rs
+++ b/hittekaart-py/src/lib.rs
@@ -1,3 +1,6 @@
+//! Python bindings for hittekaart.
+//!
+//! This module provides simple-to-use bindings for hittekaart generation from Python scripts.
 use hittekaart::gpx::{self, Compression, Coordinates};
 use hittekaart::renderer::{self, Renderer};
 use pyo3::create_exception;
@@ -11,6 +14,11 @@ use std::path::PathBuf;
 
 create_exception!(hittekaart_py, HitteError, pyo3::exceptions::PyException);
 
+/// Converts an error to a Python error.
+///
+/// This basically maps everything to [`HitteError`] and provides a stringified error explanation.
+///
+/// This recursively uses `::source()` to walk the chain.
 fn err_to_py(mut error: &dyn Error) -> PyErr {
     let mut text = error.to_string();
     loop {
@@ -23,6 +31,7 @@ fn err_to_py(mut error: &dyn Error) -> PyErr {
     HitteError::new_err(text)
 }
 
+/// Python representation of a track.
 #[pyclass]
 #[derive(Debug, Clone)]
 struct Track {
@@ -31,6 +40,9 @@ struct Track {
 
 #[pymethods]
 impl Track {
+    /// Load a track from a file.
+    ///
+    /// Compression - if given - should be one of the strings "gzip" or "brotli".
     #[staticmethod]
     fn from_file(path: &[u8], compression: Option<&str>) -> PyResult<Track> {
         let compression = match compression {
@@ -44,6 +56,7 @@ impl Track {
         Ok(Track { inner: track })
     }
 
+    /// Load a track from the given coordinates.
     #[staticmethod]
     fn from_coordinates(coordinates: Vec<(f64, f64)>) -> Track {
         Track {
@@ -53,7 +66,9 @@ impl Track {
                 .collect(),
         }
     }
+}
 
+impl Track {
     fn coordinates(&self) -> Vec<(f64, f64)> {
         self.inner
             .iter()
@@ -68,12 +83,14 @@ enum StorageType {
     Sqlite(PathBuf),
 }
 
+/// Python representation of a storage target.
 #[pyclass]
 #[derive(Debug, Clone, PartialEq, Eq)]
 struct Storage(StorageType);
 
 #[pymethods]
 impl Storage {
+    /// Output to the given folder.
     #[staticmethod]
     #[pyo3(name = "Folder")]
     fn folder(path: &[u8]) -> Self {
@@ -81,6 +98,7 @@ impl Storage {
         Storage(StorageType::Folder(path.into()))
     }
 
+    /// Output to the given sqlite file.
     #[staticmethod]
     #[pyo3(name = "Sqlite")]
     fn sqlite(path: &[u8]) -> Self {
@@ -105,6 +123,7 @@ impl Storage {
     }
 }
 
+/// Python representation of a heatmap renderer.
 #[pyclass]
 struct HeatmapRenderer {
     inner: renderer::heatmap::Renderer,
@@ -120,6 +139,11 @@ impl HeatmapRenderer {
     }
 }
 
+/// Generate the heatmap.
+///
+/// * `items` is an iterable of [`Track`]s
+/// * `renderer` should be a renderer (like [`HeatmapRenderer`])
+/// * `storage` is the [`Storage`] output
 #[pyfunction]
 fn generate(
     items: &Bound<'_, PyAny>,
-- 
cgit v1.2.3