1 files changed, 44 insertions, 0 deletions
diff --git a/src/storage.rs b/src/storage.rs
index 51a418e..9e6b270 100644
--- a/src/storage.rs
+++ b/src/storage.rs
@@ -1,3 +1,9 @@
+//! Abstractions over different storage backends.
+//!
+//! The main trait to use here is [`Storage`], which provides the necessary interface to store
+//! tiles. Usually you want to have a `dyn Storage`, and then instantiate it with a concrete
+//! implementation (either [`Folder`] or [`Sqlite`]), depending on the command line flags or
+//! similar.
 use color_eyre::{
     eyre::{bail, WrapErr},
     Result,
@@ -9,19 +15,40 @@ use std::{
     path::{Path, PathBuf},
 };
 
+/// The trait that provides the interface for storing tiles.
 pub trait Storage {
+    /// Prepare the storage.
+    ///
+    /// This can be used to e.g. ensure the directory exists, or to create the database.
     fn prepare(&mut self) -> Result<()>;
+    /// Prepare for a given zoom level.
+    ///
+    /// This function is called once per zoom, and can be used e.g. to set up the inner folder for
+    /// the level. This can avoid unnecesary syscalls if this setup would be done in
+    /// [`Storage::store`] instead.
     fn prepare_zoom(&mut self, zoom: u32) -> Result<()>;
+    /// Store the given data for the tile.
     fn store(&mut self, zoom: u32, x: u64, y: u64, data: &[u8]) -> Result<()>;
+    /// Finish the storing operation.
+    ///
+    /// This can flush any buffers, commit database changes, and so on.
     fn finish(&mut self) -> Result<()>;
 }
 
+/// Folder-based storage.
+///
+/// This stores the tiles according to the [slippy map
+/// tilenames](https://wiki.openstreetmap.org/wiki/Slippy_map_tilenames).
 #[derive(Debug)]
 pub struct Folder {
     base_dir: PathBuf,
 }
 
 impl Folder {
+    /// Create a new folder based storage.
+    ///
+    /// The given directory is the "root" directory, so a tile would be saved as
+    /// `base_dir/{zoom}/{x}/{y}.png`.
     pub fn new(base_dir: PathBuf) -> Self {
         Folder { base_dir }
     }
@@ -70,12 +97,29 @@ impl Storage for Folder {
     }
 }
 
+/// SQLite based storage.
+///
+/// This stores tiles in a SQLite database. The database will have a single table:
+///
+/// ```sql
+/// CREATE TABLE tiles (
+///     zoom INTEGER,
+///     x INTEGER,
+///     y INTEGER,
+///     data BLOB,
+///     PRIMARY KEY (zoom, x, y)
+/// );
+/// ```
 #[derive(Debug)]
 pub struct Sqlite {
     connection: Connection,
 }
 
 impl Sqlite {
+    /// Create a new SQLite backed tile store.
+    ///
+    /// The database will be saved at the given location. Note that the database must not yet
+    /// exist.
     pub fn connect<P: AsRef<Path>>(file: P) -> Result<Self> {
         let path = file.as_ref();
         if fs::metadata(path).is_ok() {