From 0642683d4702601489194aff25e9891fa46b73a6 Mon Sep 17 00:00:00 2001 From: n4n5 Date: Sun, 29 Dec 2024 15:45:47 +0100 Subject: [PATCH] add comment and force deny(missing_docs) --- walkers/src/extras/images.rs | 3 +++ walkers/src/extras/places.rs | 8 ++++++++ walkers/src/lib.rs | 2 +- walkers/src/map.rs | 8 ++++++++ walkers/src/mercator.rs | 6 ++++++ walkers/src/sources/mapbox.rs | 8 ++++++++ walkers/src/sources/mod.rs | 8 ++++++++ walkers/src/tiles.rs | 10 ++++++++++ walkers/src/zoom.rs | 1 + 9 files changed, 53 insertions(+), 1 deletion(-) diff --git a/walkers/src/extras/images.rs b/walkers/src/extras/images.rs index b0fb13b0..4594f44a 100644 --- a/walkers/src/extras/images.rs +++ b/walkers/src/extras/images.rs @@ -13,6 +13,7 @@ pub struct Image { } impl Image { + /// Create a new image. pub fn new(texture: Texture, position: Position) -> Self { Self { position, @@ -33,6 +34,7 @@ impl Image { self.angle = Rot2::from_angle(angle); } + /// Draw the image. pub fn draw(&self, ui: &Ui, projector: &crate::Projector) { let painter = ui.painter(); let rect = Rect::from_center_size( @@ -54,6 +56,7 @@ pub struct Images { } impl Images { + /// Create a new [`Images`] plugin. pub fn new(images: Vec) -> Self { Self { images } } diff --git a/walkers/src/extras/places.rs b/walkers/src/extras/places.rs index 77b45c5d..1298ff5a 100644 --- a/walkers/src/extras/places.rs +++ b/walkers/src/extras/places.rs @@ -5,12 +5,19 @@ use crate::{Plugin, Position}; /// Visual style of the place. #[derive(Clone)] pub struct Style { + /// Font used for the label. pub label_font: FontId, + /// Color of the label. pub label_color: Color32, + /// Background color of the label. pub label_background: Color32, + /// Font used for the symbol. pub symbol_font: FontId, + /// Color of the symbol. pub symbol_color: Color32, + /// Background color of the symbol. pub symbol_background: Color32, + /// Stroke of the symbol. pub symbol_stroke: Stroke, } @@ -93,6 +100,7 @@ pub struct Places { } impl Places { + /// Create a new [`Places`] plugin. pub fn new(places: Vec) -> Self { Self { places } } diff --git a/walkers/src/lib.rs b/walkers/src/lib.rs index 704ca67c..185070c7 100644 --- a/walkers/src/lib.rs +++ b/walkers/src/lib.rs @@ -1,5 +1,5 @@ #![doc = include_str!("../README.md")] -#![deny(clippy::unwrap_used, rustdoc::broken_intra_doc_links)] +#![deny(missing_docs, clippy::unwrap_used, rustdoc::broken_intra_doc_links)] mod center; mod download; diff --git a/walkers/src/map.rs b/walkers/src/map.rs index 3784ff7a..e99f8b33 100644 --- a/walkers/src/map.rs +++ b/walkers/src/map.rs @@ -56,6 +56,7 @@ pub struct Map<'a, 'b, 'c> { } impl<'a, 'b, 'c> Map<'a, 'b, 'c> { + /// Create a new map widget. pub fn new( tiles: Option<&'b mut dyn Tiles>, memory: &'a mut MapMemory, @@ -81,6 +82,12 @@ impl<'a, 'b, 'c> Map<'a, 'b, 'c> { self } + /// Set tiles manager to be used by the map. + pub fn with_tiles_manager(mut self, tiles: &'b mut dyn Tiles) -> Self { + self.tiles = Some(tiles); + self + } + /// Set whether map should perform zoom gesture. /// /// Zoom is typically triggered by the mouse wheel while holding ctrl key on native @@ -139,6 +146,7 @@ pub struct Projector { } impl Projector { + /// Create a new projector. pub fn new(clip_rect: Rect, map_memory: &MapMemory, my_position: Position) -> Self { Self { clip_rect, diff --git a/walkers/src/mercator.rs b/walkers/src/mercator.rs index b9fc014b..23c164e7 100644 --- a/walkers/src/mercator.rs +++ b/walkers/src/mercator.rs @@ -25,10 +25,12 @@ impl Position { Self(geo_types::Point::new(lon, lat)) } + /// Latitude pub fn lat(&self) -> f64 { self.0.y() } + /// Longitude pub fn lon(&self) -> f64 { self.0.x() } @@ -126,6 +128,7 @@ impl TileId { Pixels::new(self.x as f64 * tile_size, self.y as f64 * tile_size) } + /// Move to east pub fn east(&self) -> Option { Some(TileId { x: self.x + 1, @@ -134,6 +137,7 @@ impl TileId { }) } + /// Move to west pub fn west(&self) -> Option { Some(TileId { x: self.x.checked_sub(1)?, @@ -142,6 +146,7 @@ impl TileId { }) } + /// Move to north pub fn north(&self) -> Option { Some(TileId { x: self.x, @@ -150,6 +155,7 @@ impl TileId { }) } + /// Move to south pub fn south(&self) -> Option { Some(TileId { x: self.x, diff --git a/walkers/src/sources/mapbox.rs b/walkers/src/sources/mapbox.rs index ee6a9eb7..5f135fd7 100644 --- a/walkers/src/sources/mapbox.rs +++ b/walkers/src/sources/mapbox.rs @@ -6,14 +6,22 @@ use super::{Attribution, TileSource}; /// #[derive(Clone, Copy, Default)] pub enum MapboxStyle { + /// Streets Style (default) #[default] Streets, + /// Outdoors Style Outdoors, + /// Light Style Light, + /// Dark Style Dark, + /// Satellite Style Satellite, + /// Satellite Streets Style SatelliteStreets, + /// Navigation Day Style NavigationDay, + /// Navigation Night Style NavigationNight, } diff --git a/walkers/src/sources/mod.rs b/walkers/src/sources/mod.rs index b16e23d5..078c5d7c 100644 --- a/walkers/src/sources/mod.rs +++ b/walkers/src/sources/mod.rs @@ -10,16 +10,23 @@ pub use mapbox::{Mapbox, MapboxStyle}; pub use openstreetmap::OpenStreetMap; #[derive(Clone)] +/// Attribution information for the tile source. pub struct Attribution { + /// Attribution text. pub text: &'static str, + /// URL to the attribution source. pub url: &'static str, + /// Logo for the attribution. pub logo_light: Option>, + /// Dark version of the logo. pub logo_dark: Option>, } /// Remote tile server definition, source for the [`crate::HttpTiles`]. pub trait TileSource { + /// URL for the tile with the given id. fn tile_url(&self, tile_id: TileId) -> String; + /// Attribution information for the tile source. fn attribution(&self) -> Attribution; /// Size of each tile, should be a multiple of 256. @@ -27,6 +34,7 @@ pub trait TileSource { 256 } + /// Maximum zoom level. fn max_zoom(&self) -> u8 { 19 } diff --git a/walkers/src/tiles.rs b/walkers/src/tiles.rs index c4a52a53..8acffd58 100644 --- a/walkers/src/tiles.rs +++ b/walkers/src/tiles.rs @@ -13,10 +13,12 @@ pub(crate) fn rect(screen_position: Vec2, tile_size: f64) -> Rect { Rect::from_min_size(screen_position.to_pos2(), Vec2::splat(tile_size as f32)) } +/// Texture handle with a size. #[derive(Clone)] pub struct Texture(TextureHandle); impl Texture { + /// Load the texture from the image bytes. pub fn new(image: &[u8], ctx: &Context) -> Result { let image = image::load_from_memory(image)?.to_rgba8(); let pixels = image.as_flat_samples(); @@ -60,13 +62,21 @@ impl Texture { /// Texture with UV coordinates. pub struct TextureWithUv { + /// The texture. pub texture: Texture, + /// UV coordinates. pub uv: Rect, } +/// Manages the tiles cache and downloads the missing ones. pub trait Tiles { + /// Get a tile by its id fn at(&mut self, tile_id: TileId) -> Option; + + /// Attribution of the tiles source fn attribution(&self) -> Attribution; + + /// Size of each tile fn tile_size(&self) -> u32; } diff --git a/walkers/src/zoom.rs b/walkers/src/zoom.rs index cd57d2db..17bcdacf 100644 --- a/walkers/src/zoom.rs +++ b/walkers/src/zoom.rs @@ -1,3 +1,4 @@ +/// Invalid Zoom. #[derive(thiserror::Error, Debug, PartialEq, Eq)] #[error("invalid zoom level")] pub struct InvalidZoom;