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 <keavon@keavon.com>

graphene/src/layers/style/mod.rs

@@ -1,12 +1,14 @@
-use std::fmt::Write;
+//! Contains stylistic options for SVG elements.
 
 use crate::color::Color;
 use crate::consts::{LAYER_OUTLINE_STROKE_COLOR, LAYER_OUTLINE_STROKE_WIDTH};
 
-use serde::{Deserialize, Serialize};
-
 use glam::{DAffine2, DVec2};
+use serde::{Deserialize, Serialize};
+use std::fmt::Write;
 
+/// Precision of the opacity value in digits after the decimal point.
+/// A value of 3 would correspond to a precision of 10^-3.
 const OPACITY_PRECISION: usize = 3;
 
 fn format_opacity(name: &str, opacity: f32) -> String {
@@ -17,10 +19,14 @@ fn format_opacity(name: &str, opacity: f32) -> String {
 	}
 }
 
+/// Represents different ways of rendering an object
 #[derive(Debug, Clone, Copy, PartialEq, Deserialize, Serialize)]
 pub enum ViewMode {
+	/// Render with normal coloration at the current viewport resolution
 	Normal,
+	/// Render only the outlines of shapes at the current viewport resolution
 	Outline,
+	/// Render with normal coloration at the document resolution, showing the pixels when the current viewport resolution is higher
 	Pixels,
 }
 
@@ -83,7 +89,7 @@ impl Gradient {
 
 /// Describes the fill of a layer.
 ///
-/// Can be None, solid or potentially some sort of image or pattern
+/// Can be None, a solid [Color], a linear [Gradient], or potentially some sort of image or pattern in the future
 #[repr(C)]
 #[derive(Debug, Clone, PartialEq, Serialize, Deserialize)]
 pub enum Fill {
@@ -99,17 +105,17 @@ impl Default for Fill {
 }
 
 impl Fill {
-	/// Construct a new solid fill
+	/// Construct a new solid [Fill] from a [Color].
 	pub fn solid(color: Color) -> Self {
 		Self::Solid(color)
 	}
 
-	/// Evaluate the color at some point on the fill
+	/// Evaluate the color at some point on the fill. Doesn't currently work for LinearGradient.
 	pub fn color(&self) -> Color {
 		match self {
 			Self::None => Color::BLACK,
 			Self::Solid(color) => *color,
-			// ToDo: Should correctly sample the gradient
+			// TODO: Should correctly sample the gradient
 			Self::LinearGradient(Gradient { positions, .. }) => positions[0].1,
 		}
 	}
@@ -132,10 +138,13 @@ impl Fill {
 	}
 }
 
+/// The stroke (outline) style of an SVG element.
 #[repr(C)]
 #[derive(Debug, Clone, Copy, PartialEq, Serialize, Deserialize)]
 pub struct Stroke {
+	/// Stroke color
 	color: Color,
+	/// Line thickness
 	width: f32,
 }
 
@@ -144,14 +153,17 @@ impl Stroke {
 		Self { color, width }
 	}
 
+	/// Get the current stroke color.
 	pub fn color(&self) -> Color {
 		self.color
 	}
 
+	/// Get the current stroke width.
 	pub fn width(&self) -> f32 {
 		self.width
 	}
 
+	/// Provide the SVG attributes for the stroke.
 	pub fn render(&self) -> String {
 		format!(r##" stroke="#{}"{} stroke-width="{}""##, self.color.rgb_hex(), format_opacity("stroke", self.color.a()), self.width)
 	}
@@ -179,26 +191,106 @@ impl PathStyle {
 		Self { stroke, fill }
 	}
 
+	/// Get the current path's [Fill].
+	///
+	/// # Example
+	/// ```
+	/// # use graphite_graphene::layers::style::{Fill, PathStyle};
+	/// # use graphite_graphene::color::Color;
+	/// let fill = Fill::solid(Color::RED);
+	/// let style = PathStyle::new(None, fill.clone());
+	///
+	/// assert_eq!(*style.fill(), fill);
+	/// ```
 	pub fn fill(&self) -> &Fill {
 		&self.fill
 	}
 
+	/// Get the current path's [Stroke].
+	///
+	/// # Example
+	/// ```
+	/// # use graphite_graphene::layers::style::{Fill, Stroke, PathStyle};
+	/// # use graphite_graphene::color::Color;
+	/// let stroke = Stroke::new(Color::GREEN, 42.);
+	/// let style = PathStyle::new(Some(stroke), Fill::None);
+	///
+	/// assert_eq!(style.stroke(), Some(stroke));
+	/// ```
 	pub fn stroke(&self) -> Option<Stroke> {
 		self.stroke
 	}
 
+	/// Replace the path's [Fill] with a provided one.
+	///
+	/// # Example
+	/// ```
+	/// # use graphite_graphene::layers::style::{Fill, PathStyle};
+	/// # use graphite_graphene::color::Color;
+	/// let mut style = PathStyle::default();
+	///
+	/// assert_eq!(*style.fill(), Fill::None);
+	///
+	/// let fill = Fill::solid(Color::RED);
+	/// style.set_fill(fill.clone());
+	///
+	/// assert_eq!(*style.fill(), fill);
+	/// ```
 	pub fn set_fill(&mut self, fill: Fill) {
 		self.fill = fill;
 	}
 
+	/// Replace the path's [Stroke] with a provided one.
+	///
+	/// # Example
+	/// ```
+	/// # use graphite_graphene::layers::style::{Stroke, PathStyle};
+	/// # use graphite_graphene::color::Color;
+	/// let mut style = PathStyle::default();
+	///
+	/// assert_eq!(style.stroke(), None);
+	///
+	/// let stroke = Stroke::new(Color::GREEN, 42.);
+	/// style.set_stroke(stroke);
+	///
+	/// assert_eq!(style.stroke(), Some(stroke));
+	/// ```
 	pub fn set_stroke(&mut self, stroke: Stroke) {
 		self.stroke = Some(stroke);
 	}
 
+	/// Set the path's fill to None.
+	///
+	/// # Example
+	/// ```
+	/// # use graphite_graphene::layers::style::{Fill, PathStyle};
+	/// # use graphite_graphene::color::Color;
+	/// let mut style = PathStyle::new(None, Fill::Solid(Color::RED));
+	///
+	/// assert!(style.fill().is_some());
+	///
+	/// style.clear_fill();
+	///
+	/// assert!(!style.fill().is_some());
+	/// ```
 	pub fn clear_fill(&mut self) {
 		self.fill = Fill::None;
 	}
 
+	/// Set the path's stroke to None.
+	///
+	/// # Example
+	/// ```
+	/// # use graphite_graphene::layers::style::{Fill, Stroke, PathStyle};
+	/// # use graphite_graphene::color::Color;
+	/// let mut style = PathStyle::new(Some(Stroke::new(Color::GREEN, 42.)), Fill::None);
+	///
+	/// assert!(style.stroke().is_some());
+	///
+	/// style.clear_stroke();
+	///
+	/// assert!(!style.stroke().is_some());
+	/// ```
 	pub fn clear_stroke(&mut self) {
 		self.stroke = None;
 	}