From 1da0678dbbc20ba479d5aba0cfb7a08341bc8923 Mon Sep 17 00:00:00 2001 From: RustyNixieTube <49496554+RustyNixieTube@users.noreply.github.com> Date: Fri, 23 Jul 2021 16:16:26 +0200 Subject: [PATCH] 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 --- client/web/wasm/src/lib.rs | 3 ++ core/document/src/color.rs | 97 ++++++++++++++++++++++++++++++++++++-- core/document/src/lib.rs | 6 +++ core/editor/src/lib.rs | 42 ++++++++++------- core/renderer/src/lib.rs | 6 +++ 5 files changed, 133 insertions(+), 21 deletions(-) diff --git a/client/web/wasm/src/lib.rs b/client/web/wasm/src/lib.rs index 7701bec11..b50edc669 100644 --- a/client/web/wasm/src/lib.rs +++ b/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; diff --git a/core/document/src/color.rs b/core/document/src/color.rs index a6567ab0a..030622152 100644 --- a/core/document/src/color.rs +++ b/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 { - 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,) } diff --git a/core/document/src/lib.rs b/core/document/src/lib.rs index 6429e9707..e9302ded7 100644 --- a/core/document/src/lib.rs +++ b/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; diff --git a/core/editor/src/lib.rs b/core/editor/src/lib.rs index fa6351a92..a4a3e5b38 100644 --- a/core/editor/src/lib.rs +++ b/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; diff --git a/core/renderer/src/lib.rs b/core/renderer/src/lib.rs index 909562f6d..f5b05801a 100644 --- a/core/renderer/src/lib.rs +++ b/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]