Add documentation (#287)

* Add crate documentation

* Use full path intead of relative path

* Add documentation to core/document/src/color.rs

* Add modification by

* Add @Keavon's modification

* @Keavon's changes

* remove useless let

Co-authored-by: TrueDoctor <dennis@kobert.dev>

client/web/wasm/src/lib.rs

@@ -1,3 +1,6 @@
+//! **Rust WebAssembly wrapper**: `/client/web/wasm/`  
+//! Wraps the Editor Core Library and provides an API for the web app to use unburdened by Rust's complex data types that are not supported by WASM
+
 pub mod document;
 mod shims;
 pub mod utils;

core/document/src/color.rs

@@ -1,5 +1,9 @@
 use serde::{Deserialize, Serialize};
 
+/// Structure that represent a color.
+/// Internally alpha is stored as `f32` that range from `0.0` (transparent) to 1.0 (opaque).
+/// The other components (RGB) are stored as `f32` that range from `0.0` up to `f32::MAX`,
+/// the values encode the brightness of each channel proportional to the light intensity in cd/m² (nits) in HDR, and 0.0 (black) to 1.0 (white) in SDR color.
 #[repr(C)]
 #[derive(Debug, Clone, Copy, PartialEq, Default, Serialize, Deserialize)]
 pub struct Color {
@@ -16,21 +20,49 @@ impl Color {
 	pub const GREEN: Color = Color::from_unsafe(0., 1., 0.);
 	pub const BLUE: Color = Color::from_unsafe(0., 0., 1.);
 
+	/// Returns `Some(Color)` if `red`, `green`, `blue` and `alpha` have a valid value. Negatives numbers (including `-0.0`), NaN and infinity are not valid values and return `None`.
+	/// Values greater than `1.0` for alpha are not valid.
+	/// # Examples
+	/// ```
+	/// use graphite_document_core::color::Color;
+	/// let color = Color::from_rgbaf32(0.3, 0.14, 0.15, 0.92).unwrap();
+	/// assert!(color.components() == (0.3, 0.14, 0.15, 0.92));
+	///
+	/// let color = Color::from_rgbaf32(1.0, 1.0, 1.0, f32::NAN);
+	/// assert!(color == None);
+	/// ```
 	pub fn from_rgbaf32(red: f32, green: f32, blue: f32, alpha: f32) -> Option<Color> {
-		let color = Color { red, green, blue, alpha };
-		if [red, green, blue, alpha].iter().any(|c| c.is_sign_negative() || !c.is_finite()) {
+		if alpha > 1. || [red, green, blue, alpha].iter().any(|c| c.is_sign_negative() || !c.is_finite()) {
 			return None;
 		}
-		Some(color)
+		Some(Color { red, green, blue, alpha })
 	}
 
+	// Return Color without checking `red` `green` `blue` and without transparency (alpha = 1.0)
 	const fn from_unsafe(red: f32, green: f32, blue: f32) -> Color {
 		Color { red, green, blue, alpha: 1. }
 	}
 
+	/// Return a Color without transparency (alpha = 0xFF).
+	/// # Examples
+	/// ```
+	/// use graphite_document_core::color::Color;
+	/// let color = Color::from_rgb8(0x72, 0x67, 0x62);
+	/// let color2 = Color::from_rgba8(0x72, 0x67, 0x62, 0xFF);
+	/// assert!(color == color2)
+	/// ```
 	pub fn from_rgb8(red: u8, green: u8, blue: u8) -> Color {
 		Color::from_rgba8(red, green, blue, 255)
 	}
+
+	/// Return a color initialized by it's 8bit component.
+	///
+	/// # Examples
+	/// ```
+	/// use graphite_document_core::color::Color;
+	/// let color = Color::from_rgba8(0x72, 0x67, 0x62, 0x61);
+	/// assert!("72676261" == color.rgba_hex())
+	/// ```
 	pub fn from_rgba8(red: u8, green: u8, blue: u8, alpha: u8) -> Color {
 		let map = |int_color| int_color as f32 / 255.0;
 		Color {
@@ -40,21 +72,73 @@ impl Color {
 			alpha: map(alpha),
 		}
 	}
+
+	/// Return the red component.
+	///
+	/// # Examples
+	/// ```
+	/// use graphite_document_core::color::Color;
+	/// let color = Color::from_rgbaf32(0.114, 0.103, 0.98, 0.97).unwrap();
+	/// assert!(color.r() == 0.114);
+	/// ```
 	pub fn r(&self) -> f32 {
 		self.red
 	}
+
+	/// Return the green component.
+	///
+	/// # Examples
+	/// ```
+	/// use graphite_document_core::color::Color;
+	/// let color = Color::from_rgbaf32(0.114, 0.103, 0.98, 0.97).unwrap();
+	/// assert!(color.g() == 0.103);
+	/// ```
 	pub fn g(&self) -> f32 {
 		self.green
 	}
+
+	/// Return the blue component.
+	///
+	/// # Examples
+	/// ```
+	/// use graphite_document_core::color::Color;
+	/// let color = Color::from_rgbaf32(0.114, 0.103, 0.98, 0.97).unwrap();
+	/// assert!(color.b() == 0.98);
+	/// ```
 	pub fn b(&self) -> f32 {
 		self.blue
 	}
+
+	/// Return the alpha component.
+	///
+	/// # Examples
+	/// ```
+	/// use graphite_document_core::color::Color;
+	/// let color = Color::from_rgbaf32(0.114, 0.103, 0.98, 0.97).unwrap();
+	/// assert!(color.a() == 0.97);
+	/// ```
 	pub fn a(&self) -> f32 {
 		self.alpha
 	}
+
+	/// Return the all components as a tuple, first component is red, followed by green, followed by blue, followed by alpha.
+	///
+	/// # Examples
+	/// ```
+	/// use graphite_document_core::color::Color;
+	/// let color = Color::from_rgbaf32(0.114, 0.103, 0.98, 0.97).unwrap();
+	/// assert!(color.components() == (0.114, 0.103, 0.98, 0.97));
+	/// ```
 	pub fn components(&self) -> (f32, f32, f32, f32) {
 		(self.red, self.green, self.blue, self.alpha)
 	}
+
+	/// Return a String of hexadecimal value with two digit per components ("RRGGBBAA").
+	/// ```
+	/// use graphite_document_core::color::Color;
+	/// let color = Color::from_rgba8(0x72, 0x67, 0x62, 0x61);
+	/// assert!("72676261" == color.rgba_hex())
+	/// ```
 	pub fn rgba_hex(&self) -> String {
 		format!(
 			"{:02X?}{:02X?}{:02X?}{:02X?}",
@@ -64,6 +148,13 @@ impl Color {
 			(self.a() * 255.) as u8,
 		)
 	}
+
+	/// Return a String of hexadecimal value with two digit per components ("RRGGBB").
+	/// ```
+	/// use graphite_document_core::color::Color;
+	/// let color = Color::from_rgba8(0x72, 0x67, 0x62, 0x61);
+	/// assert!("726762" == color.rgb_hex())
+	/// ```
 	pub fn rgb_hex(&self) -> String {
 		format!("{:02X?}{:02X?}{:02X?}", (self.r() * 255.) as u8, (self.g() * 255.) as u8, (self.b() * 255.) as u8,)
 	}

core/document/src/lib.rs

@@ -1,3 +1,9 @@
+//! Graphite Document Core Library: `/core/document/`  
+//! A stateless library for updating Graphite design document (GDD) files.
+//! The official Graphite CLI and Editor Core Library are the primary users,
+//! but this library is intended to be useful to any application that wants to link the library for the purpose of updating GDD files by sending edit operations.
+//! Optionally depends on the Renderer Core Library if rendering is required.
+
 pub mod color;
 pub mod document;
 pub mod intersection;

core/editor/src/lib.rs

@@ -1,3 +1,9 @@
+//! **Graphite Editor Core Library**: `/core/editor/`  
+//! Used by a frontend editor client to maintain GUI state and dispatch user events.
+//! The official Graphite editor is the primary user,
+//! but others software like game engines could embed their own customized editor implementations.
+//! Depends on the Document Core Library.
+
 // since our policy is tabs, we want to stop clippy from warning about that
 #![allow(clippy::tabs_in_doc_comments)]
 
@@ -50,24 +56,24 @@ impl Editor {
 }
 
 pub mod message_prelude {
-	pub use super::communication::message::{AsMessage, Message, MessageDiscriminant};
-	pub use super::communication::{ActionList, MessageHandler};
-	pub use super::document::{DocumentMessage, DocumentMessageDiscriminant};
-	pub use super::frontend::{FrontendMessage, FrontendMessageDiscriminant};
-	pub use super::global::{GlobalMessage, GlobalMessageDiscriminant};
-	pub use super::input::{InputMapperMessage, InputMapperMessageDiscriminant, InputPreprocessorMessage, InputPreprocessorMessageDiscriminant};
-	pub use super::misc::derivable_custom_traits::{ToDiscriminant, TransitiveChild};
-	pub use super::tool::tool_messages::*;
-	pub use super::tool::tools::crop::{CropMessage, CropMessageDiscriminant};
-	pub use super::tool::tools::eyedropper::{EyedropperMessage, EyedropperMessageDiscriminant};
-	pub use super::tool::tools::fill::{FillMessage, FillMessageDiscriminant};
-	pub use super::tool::tools::line::{LineMessage, LineMessageDiscriminant};
-	pub use super::tool::tools::navigate::{NavigateMessage, NavigateMessageDiscriminant};
-	pub use super::tool::tools::path::{PathMessage, PathMessageDiscriminant};
-	pub use super::tool::tools::pen::{PenMessage, PenMessageDiscriminant};
-	pub use super::tool::tools::rectangle::{RectangleMessage, RectangleMessageDiscriminant};
-	pub use super::tool::tools::select::{SelectMessage, SelectMessageDiscriminant};
-	pub use super::tool::tools::shape::{ShapeMessage, ShapeMessageDiscriminant};
+	pub use crate::communication::message::{AsMessage, Message, MessageDiscriminant};
+	pub use crate::communication::{ActionList, MessageHandler};
+	pub use crate::document::{DocumentMessage, DocumentMessageDiscriminant};
+	pub use crate::frontend::{FrontendMessage, FrontendMessageDiscriminant};
+	pub use crate::global::{GlobalMessage, GlobalMessageDiscriminant};
+	pub use crate::input::{InputMapperMessage, InputMapperMessageDiscriminant, InputPreprocessorMessage, InputPreprocessorMessageDiscriminant};
+	pub use crate::misc::derivable_custom_traits::{ToDiscriminant, TransitiveChild};
+	pub use crate::tool::tool_messages::*;
+	pub use crate::tool::tools::crop::{CropMessage, CropMessageDiscriminant};
+	pub use crate::tool::tools::eyedropper::{EyedropperMessage, EyedropperMessageDiscriminant};
+	pub use crate::tool::tools::fill::{FillMessage, FillMessageDiscriminant};
+	pub use crate::tool::tools::line::{LineMessage, LineMessageDiscriminant};
+	pub use crate::tool::tools::navigate::{NavigateMessage, NavigateMessageDiscriminant};
+	pub use crate::tool::tools::path::{PathMessage, PathMessageDiscriminant};
+	pub use crate::tool::tools::pen::{PenMessage, PenMessageDiscriminant};
+	pub use crate::tool::tools::rectangle::{RectangleMessage, RectangleMessageDiscriminant};
+	pub use crate::tool::tools::select::{SelectMessage, SelectMessageDiscriminant};
+	pub use crate::tool::tools::shape::{ShapeMessage, ShapeMessageDiscriminant};
 	pub use crate::LayerId;
 	pub use graphite_proc_macros::*;
 	pub use std::collections::VecDeque;

core/renderer/src/lib.rs

@@ -1,3 +1,9 @@
+//! Graphite Renderer Core Library: `/core/renderer/`  
+//! A stateless library (with the help of in-memory and/or on-disk caches for performance) for rendering Graphite's render graph (GRD) files.
+//! The official Graphite CLI and Document Core Library are the primary users,
+//! but this library is intended to be useful to any application that wants to link the library for the purpose of rendering Graphite's render graphs.
+//! For example, games can link the library and render procedural textures with customizable parametric input values.
+
 #[cfg(test)]
 mod tests {
 	#[test]