From d7e9c3cc46d616c2fcd1a6e9f73adbb79c6570b4 Mon Sep 17 00:00:00 2001 From: Arne Dußin Date: Mon, 21 Dec 2020 01:22:15 +0100 Subject: Add previously missing docs where appropriate --- src/tool/deletion_tool.rs | 11 +++++++++++ src/tool/icon_tool.rs | 9 ++++++--- src/tool/mod.rs | 23 +++++++++++++++++++++++ src/tool/polygon_room_tool.rs | 5 +++++ src/tool/rect_room_tool.rs | 8 +++++++- src/tool/selection_tool.rs | 11 +++++++++++ src/tool/wall_tool.rs | 6 ++++++ 7 files changed, 69 insertions(+), 4 deletions(-) (limited to 'src/tool') diff --git a/src/tool/deletion_tool.rs b/src/tool/deletion_tool.rs index cd38f6c..afd916a 100644 --- a/src/tool/deletion_tool.rs +++ b/src/tool/deletion_tool.rs @@ -1,3 +1,11 @@ +//! A meta tool for selecting parts of a map and removing them in a single operation. +//! +//! The user can draw a rectangle, which currently must have it's side parallel to the x and y-axes +//! of the world. With the first node placement, the mode is started, while the second placement would +//! finish the process and delete all elements that are *completely* contained in the rectangle +//! (partially contained items are not deleted) or abort it, in which case the selection is removed +//! and nothing is deleted. + use super::Tool; use crate::colours::DEFAULT_COLOURS; use crate::map::Map; @@ -5,11 +13,14 @@ use crate::math::{Rect, Surface, Vec2}; use crate::transform::Transform; use raylib::core::drawing::{RaylibDraw, RaylibDrawHandle}; +/// The deletion tool itself. pub struct DeletionTool { deletion_rect: Option<(Vec2, Vec2)>, } impl DeletionTool { + /// Create a new deletion tool, there should only be one deletion tool and it should be created + /// by the editor. pub fn new() -> Self { Self { deletion_rect: None, diff --git a/src/tool/icon_tool.rs b/src/tool/icon_tool.rs index 09b0ac1..c9e671e 100644 --- a/src/tool/icon_tool.rs +++ b/src/tool/icon_tool.rs @@ -1,3 +1,6 @@ +//! Tool for creating icons. For explanation of icons, please see +//! [the icon module](crate::map::icon). + use crate::button::Button; use crate::config::IconToolKeys; use crate::map::icon_renderer::IconRenderer; @@ -8,10 +11,8 @@ use crate::transform::Transform; use raylib::core::drawing::RaylibDrawHandle; use std::rc::Rc; -pub const ICON_DIR: &str = "assets/icons"; - +/// The icon tool itself. pub struct IconTool { - // TODO: support svg keybindings: IconToolKeys, /// Saves whether the IconTool is the currently active tool or not. active: bool, @@ -22,6 +23,8 @@ pub struct IconTool { } impl IconTool { + /// Create a new icon tool that renders icons with the provided icon renderer. There should only + /// be one instance of the tool for the program, which should be created in the editor. pub fn new(keybindings: IconToolKeys, renderer: Rc) -> Self { Self { keybindings, diff --git a/src/tool/mod.rs b/src/tool/mod.rs index aeabf19..70534ac 100644 --- a/src/tool/mod.rs +++ b/src/tool/mod.rs @@ -1,3 +1,11 @@ +//! Tools, which are user interfaces that must be specifically selected in order to do something. +//! +//! As stated, a tool is not simply everything that helps a user do something, think of it more as a +//! mode which must be elected by the user to perform a task on a specific object type or a class of +//! objects. If instead the operation is defined by the state of the program, it is not a tool, since +//! the user didn't explicitly ask for this function to be performed, but it is rather an option +//! that's inherent to the situation the user finds themselves in. + pub mod deletion_tool; pub mod icon_tool; pub mod polygon_room_tool; @@ -20,16 +28,31 @@ use raylib::core::drawing::RaylibDrawHandle; #[derive(Copy, Clone, Debug, Hash, PartialEq, Eq)] #[repr(u8)] +/// The types of tools available in graf karto. For information about the tool itself, please see the +/// referenced Tool's documentation. pub enum ToolType { + /// See [super::RectRoomTool] for information on this tool. RectRoomTool, + /// See [super::PolygonRoomTool] for information on this tool. PolygonRoomTool, + /// See [super::WallTool] for information on this tool. WallTool, + /// See [super::IconTool] for information on this tool. IconTool, + /// See [super::DeletionTool] for information on this tool. DeletionTool, + /// See [super::SelectionTool] for information on this tool. SelectionTool, + /// Not a real tool but used to know how many tools are available. New tools must be added + /// above this variant. + // TODO: Since we now use a hash map in the editor, check if this is still necessary at all. NumTools, } +/// Base trait for tools. A tool is something that performs a specific action on one or more types of +/// elements. It must be selected in order to be active. For this reason, the selection tool is a +/// tool (it must be selected from the toolbox), but the dimension indicator for instance is not, +/// since it is automatically updated when applicable. pub trait Tool { /// Code that needs to be called when this Tool is activated or reactivated goes here. fn activate(&mut self) {} diff --git a/src/tool/polygon_room_tool.rs b/src/tool/polygon_room_tool.rs index de6714d..33daaf5 100644 --- a/src/tool/polygon_room_tool.rs +++ b/src/tool/polygon_room_tool.rs @@ -1,3 +1,5 @@ +//! Tool to create rooms in the shape of generic polygons. + use super::Tool; use crate::colours::DEFAULT_COLOURS; use crate::map::Map; @@ -10,6 +12,7 @@ struct UnfinishedPolygon { pub working_corner: Vec2, } +/// The tool itself. pub struct PolygonRoomTool { unfinished_polygon: Option, } @@ -76,6 +79,8 @@ impl UnfinishedPolygon { } impl PolygonRoomTool { + /// Create a new polygon room tool. There should be only one instance and it should be created + /// in the editor. pub fn new() -> Self { Self { unfinished_polygon: None, diff --git a/src/tool/rect_room_tool.rs b/src/tool/rect_room_tool.rs index 29173cd..7cb85bb 100644 --- a/src/tool/rect_room_tool.rs +++ b/src/tool/rect_room_tool.rs @@ -1,3 +1,7 @@ +//! The rectangle room tool is a specialised tool to create rooms of rectangular shape and with the +//! sides of the room parallel to the x and y-axes. This is often useful, when a quick room creation +//! is necessary and the shape of the room does not have to be very special. + use super::Tool; use crate::colours::DEFAULT_COLOURS; use crate::map::Map; @@ -5,6 +9,7 @@ use crate::math::{Rect, Vec2}; use crate::transform::Transform; use raylib::core::drawing::{RaylibDraw, RaylibDrawHandle}; +/// The tool to create simple, rectangular rooms. pub struct RectRoomTool { /// The rectangle that is currently being drawn by the user. Once it is finished, it will be /// pushed into the room_rects. @@ -12,7 +17,8 @@ pub struct RectRoomTool { } impl RectRoomTool { - /// Create a new room tool where no rooms have been drawn yet. + /// Create a new room tool where no rooms have been drawn yet. Should be created only once per + /// program instance and by the editor. pub fn new() -> Self { Self { unfinished_rect: None, diff --git a/src/tool/selection_tool.rs b/src/tool/selection_tool.rs index 30f91bf..c790734 100644 --- a/src/tool/selection_tool.rs +++ b/src/tool/selection_tool.rs @@ -1,3 +1,11 @@ +//! Selection of items on the map. +//! +//! When selecting items on the map, the editor goes into a different mode than when editing a +//! specific kind of item. Actions that are available for specific types of items become +//! unavailable, while other actions that make use of the properties to a wide range of items +//! become available instead. +//! For this reason, the selection tool can be thought of as a kind of meta tool over tools. + use super::Tool; use crate::colours::DEFAULT_COLOURS; use crate::map::Map; @@ -5,11 +13,14 @@ use crate::math::{Rect, Surface, Vec2}; use crate::transform::Transform; use raylib::core::drawing::{RaylibDraw, RaylibDrawHandle}; +/// The selection tool makes it possible to select any item on the map when activated. pub struct SelectionTool { selection_rect: Option<(Vec2, Vec2)>, } impl SelectionTool { + /// Create a new selection tool. There should be only one such tool per program instance and it + /// should be created in the editor. pub fn new() -> Self { Self { selection_rect: None, diff --git a/src/tool/wall_tool.rs b/src/tool/wall_tool.rs index b958799..123171c 100644 --- a/src/tool/wall_tool.rs +++ b/src/tool/wall_tool.rs @@ -1,3 +1,6 @@ +//! Tool to create walls. For information about walls, see also +//! [the wall module](crate::map::wall). + use super::Tool; use crate::map::Map; use crate::math::{LineSegment, Vec2}; @@ -5,11 +8,14 @@ use crate::transform::Transform; use raylib::core::drawing::{RaylibDraw, RaylibDrawHandle}; use raylib::ffi::{Color, Vector2}; +/// The wall tool to create solid barriers a player usually cannot cross. pub struct WallTool { unfinished_wall: Option>, } impl WallTool { + /// Create a new wall tool. There should only be one wall tool per program instance, which should + /// be created inside of the editor. pub fn new() -> Self { Self { unfinished_wall: None, -- cgit v1.2.3-70-g09d2