Improve the Cargo documentation (#87)

* Improve the Cargo documentation

* Fix mistakes with merge on main branch

* Fix the guide book url within the API documentation

* Update the documentation on `QuadKey`

maplibre-winit/src/input/mod.rs

@@ -56,6 +56,8 @@ impl InputController {
         false
     }
 
+    /// Process the given winit `[winit::event::WindowEvent]`.
+    /// Returns true if the event has been processed and false otherwise.
     pub fn window_input(&mut self, event: &WindowEvent) -> bool {
         match event {
             WindowEvent::CursorMoved { position, .. } => {

maplibre-winit/src/input/pan_handler.rs

@@ -97,10 +97,6 @@ impl PanHandler {
             return false;
         }
 
-        if !self.is_panning {
-            // starting to pan
-        }
-
         if *state == ElementState::Pressed {
             // currently panning or starting to pan
             self.is_panning = true;

maplibre/build.rs

@@ -1,3 +1,8 @@
+//! # Build
+//!
+//! This script is built and executed just before building the package.
+//! It will validate the WGSL (WebGPU Shading Language) shaders and embed static files.
+
 use std::path::{Path, PathBuf};
 use std::{env, fs};
 
@@ -8,7 +13,7 @@ const MUNICH_X: u32 = 17425;
 const MUNICH_Y: u32 = 11365;
 const MUNICH_Z: u8 = 15;
 
-/// Tiles which can be used by StaticTileFetcher
+/// Tiles which can be used by StaticTileFetcher.
 fn clean_static_tiles() -> PathBuf {
     let out_dir = env::var("OUT_DIR").unwrap();
 

maplibre/src/benchmarking.rs

@@ -1,7 +1,11 @@
+//! Collection of utilities used to perform certain calculations more conveniently.
+
+/// Re-export of the io module.
 pub mod io {
     pub use crate::io::*;
 }
 
+/// Re-export of the tessellation module.
 pub mod tessellation {
     pub use crate::tessellation::*;
 }

maplibre/src/coords.rs

@@ -1,4 +1,4 @@
-//! File which exposes all kinds of coordinates used throughout maplibre-rs
+//! Provides utilities related to coordinates.
 
 use std::fmt;
 use std::fmt::Formatter;
@@ -31,6 +31,11 @@ const fn create_zoom_bounds<const DIM: usize>() -> [u32; DIM] {
     result
 }
 
+/// Represents the position of a node within a quad tree. The first u8 defines the `ZoomLevel` of the node.
+/// The remaining bytes define which part (north west, south west, south east, north east) of each
+/// subdivision of the quadtree is concerned.
+///
+/// TODO: We can optimize the quadkey and store the keys on 2 bits instead of 8
 #[derive(Ord, PartialOrd, Eq, PartialEq, Clone, Copy)]
 pub struct Quadkey([u8; MAX_ZOOM]);
 
@@ -55,6 +60,8 @@ impl fmt::Debug for Quadkey {
     }
 }
 
+/// `Zoom` is an exponential scale that defines the zoom of the camera on the map.
+/// We can derive the `ZoomLevel` from `Zoom` by using the `[crate::coords::ZOOM_BOUNDS]`.
 #[derive(Copy, Clone, Debug)]
 pub struct Zoom(f64);
 
@@ -439,6 +446,7 @@ impl From<Point3<f64>> for WorldCoords {
     }
 }
 
+/// Defines a bounding box on a tiled map with a [`ZoomLevel`] and a padding.
 #[derive(Debug)]
 pub struct ViewRegion {
     min_tile: WorldTileCoords,

maplibre/src/error.rs

@@ -30,6 +30,7 @@ impl RenderError {
     }
 }
 
+/// Enumeration of errors which can happen during the operation of the library.
 #[derive(Debug)]
 pub enum Error {
     Schedule,

maplibre/src/io/geometry_index.rs

@@ -1,3 +1,5 @@
+//! Geometry index.
+
 use std::collections::{BTreeMap, HashMap};
 
 use cgmath::num_traits::Signed;
@@ -12,6 +14,7 @@ use rstar::{Envelope, PointDistance, RTree, RTreeObject, AABB};
 use crate::coords::{InnerCoords, Quadkey, WorldCoords, WorldTileCoords, Zoom, EXTENT, TILE_SIZE};
 use crate::util::math::bounds_from_points;
 
+/// A quad tree storing the currently loaded tiles.
 pub struct GeometryIndex {
     index: BTreeMap<Quadkey, TileIndex>,
 }
@@ -55,6 +58,11 @@ impl GeometryIndex {
     }
 }
 
+/// Index of tiles which can be of two types: spatial or linear.
+/// Spatial tiles are stored in a multi-dimentional tree which represents their position in the tile.
+/// Linear tiles are simply stored in a vector.
+///
+/// A spatial tile index can theoretically improve query performance on tiles. Practically it could be slower though. The `Spatial` index is experimental and currently unused.
 pub enum TileIndex {
     Spatial { tree: RTree<IndexedGeometry<f64>> },
     Linear { list: Vec<IndexedGeometry<f64>> },
@@ -85,6 +93,8 @@ impl TileIndex {
     }
 }
 
+/// An indexed geometry contains an exact vector geometry, computed bounds which
+/// can be helpful when interacting with the geometry and a hashmap of properties.
 #[derive(Debug, Clone)]
 pub struct IndexedGeometry<T>
 where
@@ -95,6 +105,7 @@ where
     pub properties: HashMap<String, String>,
 }
 
+/// Contains either a polygon or line vector.
 #[derive(Debug, Clone)]
 pub enum ExactGeometry<T>
 where
@@ -158,6 +169,7 @@ where
     }
 }
 
+/// A processor able to create geometries using `[geozero::geo_types::GeoWriter]`.
 pub struct IndexProcessor {
     geo_writer: GeoWriter,
     geometries: Vec<IndexedGeometry<f64>>,
@@ -236,36 +248,36 @@ impl PropertyProcessor for IndexProcessor {
 }
 
 impl FeatureProcessor for IndexProcessor {
-    /// Begin of dataset processing
+    /// Begin of dataset processing.
     fn dataset_begin(&mut self, _name: Option<&str>) -> Result<(), GeozeroError> {
         Ok(())
     }
-    /// End of dataset processing
+    /// End of dataset processing.
     fn dataset_end(&mut self) -> Result<(), GeozeroError> {
         Ok(())
     }
-    /// Begin of feature processing
+    /// Begin of feature processing.
     fn feature_begin(&mut self, _idx: u64) -> Result<(), GeozeroError> {
         Ok(())
     }
-    /// End of feature processing
+    /// End of feature processing.
     fn feature_end(&mut self, _idx: u64) -> Result<(), GeozeroError> {
         Ok(())
     }
-    /// Begin of feature property processing
+    /// Begin of feature property processing.
     fn properties_begin(&mut self) -> Result<(), GeozeroError> {
         self.properties = Some(HashMap::new());
         Ok(())
     }
-    /// End of feature property processing
+    /// End of feature property processing.
     fn properties_end(&mut self) -> Result<(), GeozeroError> {
         Ok(())
     }
-    /// Begin of feature geometry processing
+    /// Begin of feature geometry processing.
     fn geometry_begin(&mut self) -> Result<(), GeozeroError> {
         Ok(())
     }
-    /// End of feature geometry processing
+    /// End of feature geometry processing.
     fn geometry_end(&mut self) -> Result<(), GeozeroError> {
         let geometry = self.geo_writer.geometry().cloned().unwrap();
 

maplibre/src/io/mod.rs

@@ -18,6 +18,7 @@ pub mod shared_thread_state;
 pub mod tile_cache;
 pub mod tile_request_state;
 
+/// Contains a `Tile` if the fetch was successful otherwise `Unavailable`.
 pub enum TileFetchResult {
     Unavailable {
         coords: WorldTileCoords,
@@ -41,16 +42,20 @@ impl fmt::Debug for TileFetchResult {
     }
 }
 
+/// [crate::io::TileTessellateMessage] or [crate::io::LayerTessellateMessage] tessellation message.
 pub enum TessellateMessage {
     Tile(TileTessellateMessage),
     Layer(LayerTessellateMessage),
 }
 
+///  The result of the tessellation of a tile.
 pub struct TileTessellateMessage {
     pub request_id: TileRequestID,
     pub coords: WorldTileCoords,
 }
 
+/// `TessellatedLayer` contains the result of the tessellation for a specific layer, otherwise
+/// `UnavailableLayer` if the layer doesn't exist.
 pub enum LayerTessellateMessage {
     UnavailableLayer {
         coords: WorldTileCoords,
@@ -59,7 +64,7 @@ pub enum LayerTessellateMessage {
     TessellatedLayer {
         coords: WorldTileCoords,
         buffer: OverAlignedVertexBuffer<ShaderVertex, IndexDataType>,
-        /// Holds for each feature the count of indices
+        /// Holds for each feature the count of indices.
         feature_indices: Vec<u32>,
         layer_data: tile::Layer,
     },
@@ -87,6 +92,7 @@ impl LayerTessellateMessage {
     }
 }
 
+/// A request for a tile at the given coordinates and in the given layers.
 #[derive(Clone)]
 pub struct TileRequest {
     pub coords: WorldTileCoords,
@@ -99,4 +105,5 @@ impl fmt::Debug for TileRequest {
     }
 }
 
+/// The ID format for a tile request.
 pub type TileRequestID = u32;

maplibre/src/io/scheduler.rs

@@ -1,9 +1,12 @@
+//! Scheduling.
+
 use std::future::Future;
 
 use crate::error::Error;
 
 use crate::io::shared_thread_state::SharedThreadState;
 
+/// Async/await scheduler.
 pub struct Scheduler<SM>
 where
     SM: ScheduleMethod,
@@ -24,6 +27,7 @@ where
     }
 }
 
+/// Can schedule a task from a future factory and a shared state.
 pub trait ScheduleMethod: 'static {
     #[cfg(not(feature = "no-thread-safe-futures"))]
     fn schedule<T>(

maplibre/src/io/shared_thread_state.rs

@@ -1,3 +1,5 @@
+//! Shared thread state.
+
 use crate::coords::{WorldCoords, WorldTileCoords, Zoom};
 use crate::error::Error;
 use crate::io::geometry_index::{GeometryIndex, IndexProcessor, IndexedGeometry, TileIndex};
@@ -14,6 +16,7 @@ use geozero::GeozeroDatasource;
 use prost::Message;
 use std::sync::{mpsc, Arc, Mutex};
 
+/// Stores and provides access to the thread safe data shared between the schedulers.
 #[derive(Clone)]
 pub struct SharedThreadState {
     pub tile_request_state: Arc<Mutex<TileRequestState>>,

maplibre/src/io/source_client.rs

@@ -1,22 +1,27 @@
+//! HTTP client.
+
 use crate::coords::WorldTileCoords;
 use crate::error::Error;
 use crate::style::source::TileAddressingScheme;
 use async_trait::async_trait;
 
+/// A closure that returns a HTTP client.
 pub type HTTPClientFactory<HC> = dyn Fn() -> HC;
 
-// On the web platform futures are not thread-safe (i.e. not Send). This means we need to tell
-// async_trait that these bounds should not be placed on the async trait:
-// https://github.com/dtolnay/async-trait/blob/b70720c4c1cc0d810b7446efda44f81310ee7bf2/README.md#non-threadsafe-futures
-//
-// Users of this library can decide whether futures from the HTTPClient are thread-safe or not via
-// the future "no-thread-safe-futures". Tokio futures are thread-safe.
+/// On the web platform futures are not thread-safe (i.e. not Send). This means we need to tell
+/// async_trait that these bounds should not be placed on the async trait:
+/// [https://github.com/dtolnay/async-trait/blob/b70720c4c1cc0d810b7446efda44f81310ee7bf2/README.md#non-threadsafe-futures](https://github.com/dtolnay/async-trait/blob/b70720c4c1cc0d810b7446efda44f81310ee7bf2/README.md#non-threadsafe-futures)
+///
+/// Users of this library can decide whether futures from the HTTPClient are thread-safe or not via
+/// the future "no-thread-safe-futures". Tokio futures are thread-safe.
 #[cfg_attr(feature = "no-thread-safe-futures", async_trait(?Send))]
 #[cfg_attr(not(feature = "no-thread-safe-futures"), async_trait)]
 pub trait HTTPClient: Clone + Sync + Send + 'static {
     async fn fetch(&self, url: &str) -> Result<Vec<u8>, Error>;
 }
 
+/// Gives access to the HTTP client which can be of multiple types,
+/// see [crates::io::source_client::SourceClient]
 #[derive(Clone)]
 pub struct HttpSourceClient<HC>
 where
@@ -25,6 +30,8 @@ where
     inner_client: HC,
 }
 
+/// Defines the different types of HTTP clients such as basic HTTP and Mbtiles.
+/// More types might be coming such as S3 and other cloud http clients.
 #[derive(Clone)]
 pub enum SourceClient<HC>
 where

maplibre/src/io/static_tile_fetcher.rs

@@ -1,3 +1,5 @@
+//! Static tile fetcher
+
 use std::concat;
 use std::env;
 
@@ -13,6 +15,7 @@ static TILES: Dir = include_dir!("$OUT_DIR/extracted-tiles");
 #[cfg(not(static_tiles))]
 static TILES: Dir = Dir::new("/path", &[]);
 
+/// Load PBF files which were statically embedded in the `build.rs`
 #[derive(Default)]
 pub struct StaticTileFetcher;
 
@@ -25,10 +28,14 @@ impl StaticTileFetcher {
         Self {}
     }
 
+    /// Fetch the tile static file asynchrounously and returns a vector of bytes or a network error if the file
+    /// could not be fetched.
     pub async fn fetch_tile(&self, coords: &TileCoords) -> Result<Vec<u8>, Error> {
         self.sync_fetch_tile(coords)
     }
 
+    /// Fetch the tile static file and returns a vector of bytes or a network error if the file
+    /// could not be fetched.
     pub fn sync_fetch_tile(&self, coords: &TileCoords) -> Result<Vec<u8>, Error> {
         if TILES.entries().is_empty() {
             log::error!(

maplibre/src/io/tile_cache.rs

@@ -1,9 +1,12 @@
+//! Tile cache.
+
 use crate::coords::{Quadkey, WorldTileCoords};
 
 use crate::io::LayerTessellateMessage;
 
 use std::collections::{btree_map, BTreeMap, HashSet};
 
+/// Stores the multiple [crate::io::LayerTessellateMessage] of a cached tile.
 pub struct CachedTile {
     layers: Vec<LayerTessellateMessage>,
 }
@@ -16,6 +19,7 @@ impl CachedTile {
     }
 }
 
+/// Stores and provides access to a quad tree of cached tiles with world tile coords.
 #[derive(Default)]
 pub struct TileCache {
     cache: BTreeMap<Quadkey, CachedTile>,
@@ -28,6 +32,11 @@ impl TileCache {
         }
     }
 
+    /// Inserts a tessellated layer into the quad tree at its world tile coords.
+    /// If the space is vacant, the tessellated layer is inserted into a new
+    /// [crate::io::tile_cache::CachedTile].
+    /// If the space is occupied, the tessellated layer is added to the current
+    /// [crate::io::tile_cache::CachedTile].
     pub fn put_tessellated_layer(&mut self, message: LayerTessellateMessage) {
         if let Some(entry) = message
             .get_coords()
@@ -45,6 +54,8 @@ impl TileCache {
         }
     }
 
+    /// Returns the list of tessellated layers at the given world tile coords. None if tile is
+    /// missing from the cache.
     pub fn iter_tessellated_layers_at(
         &self,
         coords: &WorldTileCoords,
@@ -55,6 +66,8 @@ impl TileCache {
             .map(|results| results.layers.iter())
     }
 
+    /// Removes all the cached tessellate layers that are not contained within the given
+    /// layers hashset.
     pub fn retain_missing_layer_names(
         &self,
         coords: &WorldTileCoords,
@@ -71,6 +84,7 @@ impl TileCache {
         }
     }
 
+    /// Checks if a layer is missing from the given layers set at the given coords.
     pub fn is_layers_missing(&self, coords: &WorldTileCoords, layers: &HashSet<String>) -> bool {
         if let Some(cached_tile) = coords.build_quad_key().and_then(|key| self.cache.get(&key)) {
             let tessellated_set: HashSet<&str> = cached_tile

maplibre/src/io/tile_request_state.rs

@@ -1,7 +1,10 @@
+//! Tile request state.
+
 use crate::coords::WorldTileCoords;
 use crate::io::{TileRequest, TileRequestID};
 use std::collections::{HashMap, HashSet};
 
+/// Stores a map of pending requests, coords and the current tile being requested.
 #[derive(Default)]
 pub struct TileRequestState {
     current_id: TileRequestID,

maplibre/src/lib.rs

@@ -1,3 +1,21 @@
+//! # Maplibre-rs
+//!
+//! A multi-platform library for rendering vector tile maps with WebGPU.
+//!
+//! Maplibre-rs is a map renderer that can run natively on MacOS, Linux, Windows, Android, iOS and the web.
+//! It takes advantage of Lyon to tessellate vector tiles and WebGPU to display them efficiently.
+//! Maplibre-rs also has an headless mode (*work in progress*) that can generate rasters.
+//!
+//! The official guide book can be found [here](https://maxammann.org/maplibre-rs/docs/).
+//!
+//! ### Example
+//!
+//! To import maplibre-rs in your `Cargo.toml`:
+//!
+//! ```toml
+//! maplibre = "0.0.2"
+//! ```
+
 use crate::io::scheduler::{ScheduleMethod, Scheduler};
 use crate::io::source_client::HTTPClient;
 use crate::map_state::MapState;
@@ -23,6 +41,7 @@ pub(crate) mod tessellation;
 pub(crate) mod tilejson;
 pub(crate) mod util;
 
+/// Map's configuration and execution.
 pub struct Map<W, SM, HC>
 where
     W: MapWindow,
@@ -39,19 +58,34 @@ where
     SM: ScheduleMethod,
     HC: HTTPClient,
 {
+    /// Starts the [`crate::map_state::MapState`] Runnable with the configured event loop.
     pub fn run(self) {
         self.run_with_optionally_max_frames(None);
     }
 
+    /// Starts the [`crate::map_state::MapState`] Runnable with the configured event loop.
+    ///
+    /// # Arguments
+    ///
+    /// * `max_frames` - Maximum number of frames per second.
     pub fn run_with_max_frames(self, max_frames: u64) {
         self.run_with_optionally_max_frames(Some(max_frames));
     }
 
+    /// Starts the MapState Runnable with the configured event loop.
+    ///
+    /// # Arguments
+    ///
+    /// * `max_frames` - Optional maximum number of frames per second.
     pub fn run_with_optionally_max_frames(self, max_frames: Option<u64>) {
         self.window.run(self.map_state, max_frames);
     }
 }
 
+/// Stores the map configuration before the map's state has been fully initialized.
+///
+/// FIXME: We could maybe remove this class, and store the render_state in an Optional in [`crate::map_state::MapState`].
+/// FIXME: I think we can find a workaround so that this class doesn't exist.
 pub struct UninitializedMap<MWC, SM, HC>
 where
     MWC: MapWindowConfig,
@@ -71,6 +105,8 @@ where
     SM: ScheduleMethod,
     HC: HTTPClient,
 {
+    /// Initializes the whole rendering pipeline for the given configuration.
+    /// Returns the initialized map, ready to be run.
     pub async fn initialize(self) -> Map<MWC::MapWindow, SM, HC> {
         let instance = wgpu::Instance::new(wgpu::Backends::all());
         //let instance = wgpu::Instance::new(wgpu::Backends::GL);
@@ -157,6 +193,7 @@ where
         self
     }
 
+    /// Builds the UninitializedMap with the given configuration.
     pub fn build(self) -> UninitializedMap<MWC, SM, HC> {
         let scheduler = self
             .scheduler

maplibre/src/map_state.rs

@@ -1,3 +1,5 @@
+//! Stores the state of the map such as `[crate::coords::Zoom]`, `[crate::camera::Camera]`, `[crate::style::Style]`, `[crate::io::tile_cache::TileCache]` and more.
+
 use crate::coords::{ViewRegion, WorldTileCoords, Zoom, TILE_SIZE};
 use crate::error::Error;
 use crate::io::geometry_index::GeometryIndex;
@@ -14,9 +16,9 @@ use crate::style::Style;
 use crate::util::ChangeObserver;
 use crate::{MapWindow, MapWindowConfig, ScheduleMethod, WindowSize};
 use std::collections::HashSet;
-
 use std::sync::{mpsc, Arc, Mutex};
 
+/// Stores the camera configuration.
 pub struct ViewState {
     zoom: ChangeObserver<Zoom>,
     pub camera: ChangeObserver<Camera>,
@@ -42,6 +44,10 @@ impl ViewState {
     }
 }
 
+/// Stores the state of the map, dispatches tile fetching and caching, tessellation and drawing.
+///
+/// FIXME: MapState may not follow the Single-responsibility principle, as it not only stores
+/// the state of the map but also the rendering, caching, etc.
 pub struct MapState<MWC, SM, HC>
 where
     MWC: MapWindowConfig,
@@ -164,7 +170,7 @@ where
         }
     }
 
-    /// Request tiles which are currently in view
+    /// Request tiles which are currently in view.
     #[tracing::instrument(skip_all)]
     fn request_tiles_in_view(&mut self, view_region: &ViewRegion) -> bool {
         let mut try_failed = false;

maplibre/src/platform/mod.rs

@@ -1,5 +1,5 @@
-//! This module handles platform specific code. Depending on the compilation target different
-//! parts of this module are used
+//! Handles platform specific code. Depending on the compilation target, different
+//! parts of this module are used.
 
 // WebGPU
 #[cfg(all(target_arch = "wasm32", not(feature = "web-webgl")))]
@@ -13,7 +13,7 @@ pub const COLOR_TEXTURE_FORMAT: wgpu::TextureFormat = wgpu::TextureFormat::Rgba8
 #[cfg(target_os = "android")]
 pub const COLOR_TEXTURE_FORMAT: wgpu::TextureFormat = wgpu::TextureFormat::Rgba8Unorm;
 
-// macOS and iOS (Metal)
+/// MacOS and iOS (Metal).
 #[cfg(any(target_os = "macos", target_os = "ios"))]
 pub const COLOR_TEXTURE_FORMAT: wgpu::TextureFormat = wgpu::TextureFormat::Bgra8UnormSrgb;
 
@@ -29,11 +29,13 @@ pub const COLOR_TEXTURE_FORMAT: wgpu::TextureFormat = wgpu::TextureFormat::Bgra8
 #[cfg(not(target_arch = "wasm32"))]
 mod noweb;
 
+/// Http client for non-web targets.
 pub mod http_client {
     #[cfg(not(target_arch = "wasm32"))]
     pub use super::noweb::http_client::*;
 }
 
+/// Scheduler for non-web targets.
 pub mod schedule_method {
     #[cfg(not(target_arch = "wasm32"))]
     pub use super::noweb::schedule_method::*;
@@ -42,6 +44,8 @@ pub mod schedule_method {
 #[cfg(not(target_arch = "wasm32"))]
 pub use noweb::run_multithreaded;
 
-// FIXME: This limit is enforced by WebGL. Actually this makes sense!
-// FIXME: This can also be achieved by _pad attributes in shader_ffi.rs
+/// Minimum WebGPU buffer size
+///
+/// FIXME: This limit is enforced by WebGL. Actually this makes sense!
+/// FIXME: This can also be achieved by _pad attributes in shader_ffi.rs
 pub const MIN_BUFFER_SIZE: u64 = 32;

maplibre/src/platform/noweb/schedule_method.rs

@@ -3,6 +3,7 @@ use crate::io::shared_thread_state::SharedThreadState;
 use crate::ScheduleMethod;
 use std::future::Future;
 
+/// Multi-threading with Tokio.
 pub struct TokioScheduleMethod;
 
 impl TokioScheduleMethod {

maplibre/src/render/texture.rs

@@ -32,7 +32,7 @@ impl Texture {
         }
     }
 
-    /// Creates a texture that uses MSAA and fits a given swap chain
+    /// Creates a texture that uses MSAA and fits a given swap chain.
     pub fn create_multisampling_texture(
         device: &wgpu::Device,
         desc: &wgpu::SurfaceConfiguration,

maplibre/src/style/layer.rs

@@ -1,3 +1,5 @@
+//! Vector tile layer drawing utilities.
+
 use cint::{Alpha, EncodedSrgb};
 use csscolorparser::Color;
 use serde::{Deserialize, Serialize};
@@ -27,6 +29,7 @@ pub struct LinePaint {
     // TODO a lot
 }
 
+/// The different types of paints.
 #[derive(Serialize, Deserialize, Debug, Clone)]
 #[serde(tag = "type", content = "paint")]
 pub enum LayerPaint {
@@ -51,6 +54,7 @@ impl LayerPaint {
     }
 }
 
+/// Stores all the styles for a specific layer.
 #[derive(Serialize, Deserialize, Debug, Clone)]
 pub struct StyleLayer {
     #[serde(skip)]

maplibre/src/style/mod.rs

@@ -1,3 +1,5 @@
+//! Vector tile format styling.
+
 pub mod layer;
 pub mod source;
 mod style;

maplibre/src/style/source.rs

@@ -1,9 +1,14 @@
+//! Vector tile data utilities.
+
 use serde::{Deserialize, Serialize};
 
+/// String url to a tile.
 pub type TileUrl = String;
 
+/// String url to a JSON tile.
 pub type TileJSONUrl = String;
 
+/// Tiles can be positioned using either the xyz coordinates or the TMS (Tile Map Service) protocol.
 #[derive(Serialize, Deserialize, Debug, Clone)]
 pub enum TileAddressingScheme {
     #[serde(rename = "xyz")]
@@ -18,18 +23,19 @@ impl Default for TileAddressingScheme {
     }
 }
 
+/// Source properties for tiles or rasters.
 #[derive(Serialize, Deserialize, Debug, Clone)]
 pub struct VectorSource {
-    /// String which contains attribution information for the used tiles
+    /// String which contains attribution information for the used tiles.
     #[serde(skip_serializing_if = "Option::is_none")]
     pub attribution: Option<String>,
-    /// The bounds in which tiles are available
+    /// The bounds in which tiles are available.
     #[serde(skip_serializing_if = "Option::is_none")]
     pub bounds: Option<(f64, f64, f64, f64)>,
-    /// Max zoom level at which tiles are available
+    /// Max zoom level at which tiles are available.
     #[serde(skip_serializing_if = "Option::is_none")]
     pub maxzoom: Option<u8>,
-    /// Min zoom level at which tiles are available
+    /// Min zoom level at which tiles are available.
     #[serde(skip_serializing_if = "Option::is_none")]
     pub minzoom: Option<u8>,
     // TODO: promoteId
@@ -49,5 +55,5 @@ pub enum Source {
     #[serde(rename = "vector")]
     Vector(VectorSource),
     #[serde(rename = "raster")]
-    Raster(VectorSource),
+    Raster(VectorSource), // FIXME: Does it make sense that a raster have a VectorSource?
 }

maplibre/src/style/style.rs

@@ -1,3 +1,5 @@
+//! Default vector tile styles configuration.
+
 use crate::style::layer::{LayerPaint, LinePaint, StyleLayer};
 use crate::style::source::Source;
 use csscolorparser::Color;
@@ -5,6 +7,7 @@ use serde::{Deserialize, Serialize};
 use std::collections::HashMap;
 use std::str::FromStr;
 
+/// Stores the style for a multi-layered map.
 #[derive(Serialize, Deserialize, Debug, Clone)]
 pub struct Style {
     pub version: u16,

maplibre/src/tessellation/mod.rs

@@ -15,8 +15,10 @@ pub mod zero_tessellator;
 
 const DEFAULT_TOLERANCE: f32 = 0.02;
 
+/// Vertex buffers index data type.
 pub type IndexDataType = u32; // Must match INDEX_FORMAT
 
+/// An element that can be tessellated into vertex buffers.
 pub trait Tessellated<I: Add> {
     /// Returns a vertex buffer which represents some object like a layer. Each object can contain
     /// multiple features. For each feature also the amount of indices is returned.
@@ -24,6 +26,7 @@ pub trait Tessellated<I: Add> {
     fn tessellate(&self) -> Result<(VertexBuffers<ShaderVertex, I>, Vec<u32>), Error>;
 }
 
+/// Constructor for Fill and Stroke vertices.
 pub struct VertexConstructor {}
 
 impl FillVertexConstructor<ShaderVertex> for VertexConstructor {

maplibre/src/tessellation/zero_tessellator.rs

@@ -1,3 +1,5 @@
+//! Tessellator implementation.
+
 use geozero::{FeatureProcessor, GeomProcessor, PropertyProcessor};
 use lyon::geom;
 
@@ -15,6 +17,7 @@ use crate::tessellation::{VertexConstructor, DEFAULT_TOLERANCE};
 
 type GeoResult<T> = geozero::error::Result<T>;
 
+/// Build tessellations with vectors.
 pub struct ZeroTessellator<I: std::ops::Add + From<lyon::tessellation::VertexId> + MaxIndex> {
     path_builder: RefCell<Builder>,
     path_open: bool,

maplibre/src/window.rs

@@ -1,5 +1,8 @@
+//! Utilities for the window system.
+
 use crate::{HTTPClient, MapState, ScheduleMethod};
 
+/// Window with an optional [carte::window::WindowSize].
 pub trait MapWindow {
     type EventLoop;
     type Window: raw_window_handle::HasRawWindowHandle;
@@ -25,6 +28,7 @@ where
     fn run(self, map_state: MapState<MWC, SM, HC>, max_frames: Option<u64>);
 }
 
+/// Window size with a width and an height in pixels.
 #[derive(Clone, Copy)]
 pub struct WindowSize {
     width: u32,

web/src/platform/pool.rs

@@ -62,7 +62,7 @@ impl WorkerPool {
         Ok(pool)
     }
 
-    /// Unconditionally spawns a new worker
+    /// Unconditionally spawns a new worker.
     ///
     /// The worker isn't registered with this `WorkerPool` but is capable of
     /// executing work for this wasm module.