Add documentation to many parts of the Rust codebase (#552)

* add lots of doccomments

* add conversion traits from layerdatatypes to layers

* add suggested doc improvements

* Code review changes

Co-authored-by: Keavon Chambers <[email protected]>

Author: simonwuelker

graphene/src/document.rs

@@ -16,10 +16,13 @@ use std::cmp::max;
 use std::collections::hash_map::DefaultHasher;
 use std::hash::{Hash, Hasher};
 
+/// A number that identifies a layer.
+/// This does not technically need to be unique globally, only within a folder.
 pub type LayerId = u64;
 
 #[derive(Debug, Clone, Deserialize, Serialize)]
 pub struct Document {
+	/// The root layer, usually a [FolderLayer](layers::folder_layer::FolderLayer) that contains all other [Layers](layers::layer_info::Layer).
 	pub root: Layer,
 	/// The state_identifier serves to provide a way to uniquely identify a particular state that the document is in.
 	/// This identifier is not a hash and is not guaranteed to be equal for equivalent documents.
@@ -338,6 +341,7 @@ impl Document {
 		boxes.reduce(|a, b| [a[0].min(b[0]), a[1].max(b[1])])
 	}
 
+	/// Mark the layer at the provided path, as well as all the folders containing it, as dirty.
 	pub fn mark_upstream_as_dirty(&mut self, path: &[LayerId]) -> Result<(), DocumentError> {
 		let mut root = &mut self.root;
 		root.cache_dirty = true;

graphene/src/error.rs

@@ -1,6 +1,7 @@
 use super::LayerId;
 use crate::boolean_ops::BooleanOperationError;
 
+/// A set of different errors that can occur when using Graphene.
 #[derive(Debug, Clone, PartialEq)]
 pub enum DocumentError {
 	LayerNotFound(Vec<LayerId>),

graphene/src/intersection.rs

@@ -10,14 +10,17 @@ use glam::{DAffine2, DMat2, DVec2};
 use kurbo::{BezPath, CubicBez, Line, ParamCurve, ParamCurveExtrema, PathSeg, Point, QuadBez, Rect, Shape, Vec2};
 
 #[derive(Debug, Clone, Default, Copy)]
+/// A quad defined by four vertices.
 pub struct Quad([DVec2; 4]);
 
 impl Quad {
+	/// Convert a box defined by two corner points to a quad.
 	pub fn from_box(bbox: [DVec2; 2]) -> Self {
 		let size = bbox[1] - bbox[0];
 		Self([bbox[0], bbox[0] + size * DVec2::X, bbox[1], bbox[0] + size * DVec2::Y])
 	}
 
+	/// Get all the edges in the quad.
 	pub fn lines(&self) -> [Line; 4] {
 		[
 			Line::new(to_point(self.0[0]), to_point(self.0[1])),
@@ -27,6 +30,7 @@ impl Quad {
 		]
 	}
 
+	/// Generate a [BezPath] of the quad
 	pub fn path(&self) -> BezPath {
 		let mut path = kurbo::BezPath::new();
 		path.move_to(to_point(self.0[0]));
@@ -54,6 +58,11 @@ fn to_point(vec: DVec2) -> Point {
 	Point::new(vec.x, vec.y)
 }
 
+/// Return `true` if `quad` intersects `shape`.
+/// This is the case if any of the following conditions are true:
+/// * the edges of `quad` and `shape` intersect
+/// * `shape` is entirely contained within `quad`
+/// * `filled` is `true` and `quad` is entirely contained within `shape`.
 pub fn intersect_quad_bez_path(quad: Quad, shape: &BezPath, filled: bool) -> bool {
 	let mut shape = shape.clone();
 	// for filled shapes act like shape was closed even if it isn't
@@ -74,6 +83,8 @@ pub fn intersect_quad_bez_path(quad: Quad, shape: &BezPath, filled: bool) -> boo
 	get_arbitrary_point_on_path(&shape).map(|shape_point| quad.path().contains(shape_point)).unwrap_or_default()
 }
 
+/// Returns a point on `path`.
+/// This function will usually return the first point from the path's first segment, but callers should not rely on this behavior.
 pub fn get_arbitrary_point_on_path(path: &BezPath) -> Option<Point> {
 	path.segments().next().map(|seg| match seg {
 		PathSeg::Line(line) => line.p0,
@@ -640,7 +651,7 @@ pub fn quad_line_intersect(a: &Line, b: &QuadBez) -> [Option<f64>; 2] {
 }
 
 /// Returns real roots to cubic equation: `f(t) = a0 + t*a1 + t^2*a2 + t^3*a3`.
-/// This function uses the Cardano-Viete and Numerical Recipes algorithm, found here: https://quarticequations.com/Cubic.pdf
+/// This function uses the Cardano-Viete and Numerical Recipes algorithm, found here: <https://quarticequations.com/Cubic.pdf>
 pub fn cubic_real_roots(mut a0: f64, mut a1: f64, mut a2: f64, a3: f64) -> [Option<f64>; 3] {
 	use std::f64::consts::FRAC_PI_3 as PI_3;
 

graphene/src/layers/blend_mode.rs

@@ -1,5 +1,7 @@
 use serde::{Deserialize, Serialize};
 
+/// Describes how overlapping SVG elements should be blended together.
+/// See the [MDN Docs](https://developer.mozilla.org/en-US/docs/Web/CSS/blend-mode#examples) for examples.
 #[derive(PartialEq, Copy, Clone, Debug, Serialize, Deserialize)]
 pub enum BlendMode {
 	Normal,
@@ -21,6 +23,8 @@ pub enum BlendMode {
 }
 
 impl BlendMode {
+	/// Convert the enum to the CSS string for the blend mode.
+	/// [Read more](https://developer.mozilla.org/en-US/docs/Web/CSS/blend-mode#values)
 	pub fn to_svg_style_name(&self) -> &str {
 		match self {
 			BlendMode::Normal => "normal",

graphene/src/layers/folder_layer.rs

@@ -7,10 +7,16 @@ use glam::DVec2;
 use serde::{Deserialize, Serialize};
 use std::fmt::Write;
 
+/// A layer that encapsulates other layers, including potentially more folders.
+/// The contained layers are rendered in the same order they are
+/// stored in the [layers](FolderLayer::layers) field.
 #[derive(Debug, Clone, PartialEq, Deserialize, Serialize, Default)]
 pub struct FolderLayer {
+	/// The ID that will be assigned to the next layer that is added to the folder
 	next_assignment_id: LayerId,
+	/// The IDs of the [Layer]s contained within the Folder
 	pub layer_ids: Vec<LayerId>,
+	/// The [Layer]s contained in the folder
 	layers: Vec<Layer>,
 }
 
@@ -38,12 +44,29 @@ impl LayerData for FolderLayer {
 }
 
 impl FolderLayer {
-	/// When a insertion id is provided, try to insert the layer with the given id.
-	/// If that id is already used, return None.
-	/// When no insertion id is provided, search for the next free id and insert it with that.
-	/// Negative values for insert_index represent distance from the end
+	/// When a insertion ID is provided, try to insert the layer with the given ID.
+	/// If that ID is already used, return `None`.
+	/// When no insertion ID is provided, search for the next free ID and insert it with that.
+	/// Negative values for `insert_index` represent distance from the end
+	///
+	/// # Example
+	/// ```
+	/// # use graphite_graphene::layers::shape_layer::ShapeLayer;
+	/// # use graphite_graphene::layers::folder_layer::FolderLayer;
+	/// # use graphite_graphene::layers::style::PathStyle;
+	/// # use graphite_graphene::layers::layer_info::LayerDataType;
+	/// let mut folder = FolderLayer::default();
+	///
+	/// // Create two layers to be added to the folder
+	/// let mut shape_layer = ShapeLayer::rectangle(PathStyle::default());
+	/// let mut folder_layer = FolderLayer::default();
+	///
+	/// folder.add_layer(shape_layer.into(), None, -1);
+	/// folder.add_layer(folder_layer.into(), Some(123), 0);
+	/// ```
 	pub fn add_layer(&mut self, layer: Layer, id: Option<LayerId>, insert_index: isize) -> Option<LayerId> {
 		let mut insert_index = insert_index as i128;
+
 		if insert_index < 0 {
 			insert_index = self.layers.len() as i128 + insert_index as i128 + 1;
 		}
@@ -71,22 +94,42 @@ impl FolderLayer {
 		}
 	}
 
+	/// Remove a layer with a given ID from the folder.
+	/// This operation will fail if `id` is not present in the folder.
+	///
+	/// # Example
+	/// ```
+	/// # use graphite_graphene::layers::folder_layer::FolderLayer;
+	/// let mut folder = FolderLayer::default();
+	///
+	/// // Try to remove a layer that does not exist
+	/// assert!(folder.remove_layer(123).is_err());
+	///
+	/// // Add another folder to the folder
+	/// folder.add_layer(FolderLayer::default().into(), Some(123), -1);
+	///
+	/// // Try to remove that folder again
+	/// assert!(folder.remove_layer(123).is_ok());
+	/// assert_eq!(folder.layers().len(), 0)
+	/// ```
 	pub fn remove_layer(&mut self, id: LayerId) -> Result<(), DocumentError> {
 		let pos = self.position_of_layer(id)?;
 		self.layers.remove(pos);
 		self.layer_ids.remove(pos);
 		Ok(())
 	}
 
-	/// Returns a list of layers in the folder
+	/// Returns a list of [LayerId]s in the folder.
 	pub fn list_layers(&self) -> &[LayerId] {
 		self.layer_ids.as_slice()
 	}
 
+	/// Get references to all the [Layer]s in the folder.
 	pub fn layers(&self) -> &[Layer] {
 		self.layers.as_slice()
 	}
 
+	/// Get mutable references to all the [Layer]s in the folder.
 	pub fn layers_mut(&mut self) -> &mut [Layer] {
 		self.layers.as_mut_slice()
 	}
@@ -101,14 +144,70 @@ impl FolderLayer {
 		Some(&mut self.layers[pos])
 	}
 
+	/// Returns `true` if the folder contains a layer with the given [LayerId].
+	///
+	/// # Example
+	/// ```
+	/// # use graphite_graphene::layers::folder_layer::FolderLayer;
+	/// let mut folder = FolderLayer::default();
+	///
+	/// // Search for an id that does not exist
+	/// assert!(!folder.folder_contains(123));
+	///
+	/// // Add layer with the id "123" to the folder
+	/// folder.add_layer(FolderLayer::default().into(), Some(123), -1);
+	///
+	/// // Search for the id "123"
+	/// assert!(folder.folder_contains(123));
+	/// ```
 	pub fn folder_contains(&self, id: LayerId) -> bool {
 		self.layer_ids.contains(&id)
 	}
 
+	/// Tries to find the index of a layer with the given [LayerId] within the folder.
+	/// This operation will fail if no layer with a matching ID is present in the folder.
+	///
+	/// # Example
+	/// ```
+	/// # use graphite_graphene::layers::folder_layer::FolderLayer;
+	/// let mut folder = FolderLayer::default();
+	///
+	/// // Search for an id that does not exist
+	/// assert!(folder.position_of_layer(123).is_err());
+	///
+	/// // Add layer with the id "123" to the folder
+	/// folder.add_layer(FolderLayer::default().into(), Some(123), -1);
+	/// folder.add_layer(FolderLayer::default().into(), Some(42), -1);
+	///
+	/// assert_eq!(folder.position_of_layer(123), Ok(0));
+	/// assert_eq!(folder.position_of_layer(42), Ok(1));
+	/// ```
 	pub fn position_of_layer(&self, layer_id: LayerId) -> Result<usize, DocumentError> {
 		self.layer_ids.iter().position(|x| *x == layer_id).ok_or_else(|| DocumentError::LayerNotFound([layer_id].into()))
 	}
 
+	/// Tries to get a reference to a folder with the given [LayerId].
+	/// This operation will return `None` if either no layer with `id` exists
+	/// in the folder, or the layer with matching ID is not a folder.
+	///
+	/// # Example
+	/// ```
+	/// # use graphite_graphene::layers::folder_layer::FolderLayer;
+	/// # use graphite_graphene::layers::shape_layer::ShapeLayer;
+	/// # use graphite_graphene::layers::style::PathStyle;
+	/// let mut folder = FolderLayer::default();
+	///
+	/// // Search for an id that does not exist
+	/// assert!(folder.folder(132).is_none());
+	///
+	/// // add a folder and search for it
+	/// folder.add_layer(FolderLayer::default().into(), Some(123), -1);
+	/// assert!(folder.folder(123).is_some());
+	///
+	/// // add a non-folder layer and search for it
+	/// folder.add_layer(ShapeLayer::rectangle(PathStyle::default()).into(), Some(42), -1);
+	/// assert!(folder.folder(42).is_none());
+	/// ```
 	pub fn folder(&self, id: LayerId) -> Option<&FolderLayer> {
 		match self.layer(id) {
 			Some(Layer {
@@ -118,6 +217,10 @@ impl FolderLayer {
 		}
 	}
 
+	/// Tries to get a mutable reference to folder with the given `id`.
+	/// This operation will return `None` if either no layer with `id` exists
+	/// in the folder or the layer with matching ID is not a folder.
+	/// See the [FolderLayer::folder] method for a usage example.
 	pub fn folder_mut(&mut self, id: LayerId) -> Option<&mut FolderLayer> {
 		match self.layer_mut(id) {
 			Some(Layer {