From 825518564af92a3c11393e2b4ccb96547899764c Mon Sep 17 00:00:00 2001 From: Rob Parrett Date: Tue, 2 Aug 2022 00:04:49 +0000 Subject: [PATCH] Add docs for arguments of various color functions (#5533) Fixes #5530 --- crates/bevy_render/src/color/mod.rs | 109 +++++++++++++++++++++++++--- 1 file changed, 97 insertions(+), 12 deletions(-) diff --git a/crates/bevy_render/src/color/mod.rs b/crates/bevy_render/src/color/mod.rs index d0eb1846da..a00481ffbb 100644 --- a/crates/bevy_render/src/color/mod.rs +++ b/crates/bevy_render/src/color/mod.rs @@ -14,35 +14,35 @@ use thiserror::Error; pub enum Color { /// sRGBA color Rgba { - /// Red component. [0.0, 1.0] + /// Red channel. [0.0, 1.0] red: f32, - /// Green component. [0.0, 1.0] + /// Green channel. [0.0, 1.0] green: f32, - /// Blue component. [0.0, 1.0] + /// Blue channel. [0.0, 1.0] blue: f32, - /// Alpha component. [0.0, 1.0] + /// Alpha channel. [0.0, 1.0] alpha: f32, }, /// RGBA color in the Linear sRGB colorspace (often colloquially referred to as "linear", "RGB", or "linear RGB"). RgbaLinear { - /// Red component. [0.0, 1.0] + /// Red channel. [0.0, 1.0] red: f32, - /// Green component. [0.0, 1.0] + /// Green channel. [0.0, 1.0] green: f32, - /// Blue component. [0.0, 1.0] + /// Blue channel. [0.0, 1.0] blue: f32, - /// Alpha component. [0.0, 1.0] + /// Alpha channel. [0.0, 1.0] alpha: f32, }, /// HSL (hue, saturation, lightness) color with an alpha channel Hsla { - /// Hue component. [0.0, 360.0] + /// Hue channel. [0.0, 360.0] hue: f32, - /// Saturation component. [0.0, 1.0] + /// Saturation channel. [0.0, 1.0] saturation: f32, - /// Lightness component. [0.0, 1.0] + /// Lightness channel. [0.0, 1.0] lightness: f32, - /// Alpha component. [0.0, 1.0] + /// Alpha channel. [0.0, 1.0] alpha: f32, }, } @@ -126,6 +126,15 @@ impl Color { pub const YELLOW_GREEN: Color = Color::rgb(0.6, 0.8, 0.2); /// New `Color` from sRGB colorspace. + /// + /// # Arguments + /// + /// * `r` - Red channel. [0.0, 1.0] + /// * `g` - Green channel. [0.0, 1.0] + /// * `b` - Blue channel. [0.0, 1.0] + /// + /// See also [`Color::rgba`], [`Color::rgb_u8`], [`Color::hex`]. + /// pub const fn rgb(r: f32, g: f32, b: f32) -> Color { Color::Rgba { red: r, @@ -136,6 +145,16 @@ impl Color { } /// New `Color` from sRGB colorspace. + /// + /// # Arguments + /// + /// * `r` - Red channel. [0.0, 1.0] + /// * `g` - Green channel. [0.0, 1.0] + /// * `b` - Blue channel. [0.0, 1.0] + /// * `a` - Alpha channel. [0.0, 1.0] + /// + /// See also [`Color::rgb`], [`Color::rgba_u8`], [`Color::hex`]. + /// pub const fn rgba(r: f32, g: f32, b: f32, a: f32) -> Color { Color::Rgba { red: r, @@ -146,6 +165,15 @@ impl Color { } /// New `Color` from linear RGB colorspace. + /// + /// # Arguments + /// + /// * `r` - Red channel. [0.0, 1.0] + /// * `g` - Green channel. [0.0, 1.0] + /// * `b` - Blue channel. [0.0, 1.0] + /// + /// See also [`Color::rgb`], [`Color::rgba_linear`]. + /// pub const fn rgb_linear(r: f32, g: f32, b: f32) -> Color { Color::RgbaLinear { red: r, @@ -156,6 +184,16 @@ impl Color { } /// New `Color` from linear RGB colorspace. + /// + /// # Arguments + /// + /// * `r` - Red channel. [0.0, 1.0] + /// * `g` - Green channel. [0.0, 1.0] + /// * `b` - Blue channel. [0.0, 1.0] + /// * `a` - Alpha channel. [0.0, 1.0] + /// + /// See also [`Color::rgba`], [`Color::rgb_linear`]. + /// pub const fn rgba_linear(r: f32, g: f32, b: f32, a: f32) -> Color { Color::RgbaLinear { red: r, @@ -166,6 +204,15 @@ impl Color { } /// New `Color` with HSL representation in sRGB colorspace. + /// + /// # Arguments + /// + /// * `hue` - Hue channel. [0.0, 360.0] + /// * `saturation` - Saturation channel. [0.0, 1.0] + /// * `lightness` - Lightness channel. [0.0, 1.0] + /// + /// See also [`Color::hsla`]. + /// pub const fn hsl(hue: f32, saturation: f32, lightness: f32) -> Color { Color::Hsla { hue, @@ -176,6 +223,16 @@ impl Color { } /// New `Color` with HSL representation in sRGB colorspace. + /// + /// # Arguments + /// + /// * `hue` - Hue channel. [0.0, 360.0] + /// * `saturation` - Saturation channel. [0.0, 1.0] + /// * `lightness` - Lightness channel. [0.0, 1.0] + /// * `alpha` - Alpha channel. [0.0, 1.0] + /// + /// See also [`Color::hsl`]. + /// pub const fn hsla(hue: f32, saturation: f32, lightness: f32, alpha: f32) -> Color { Color::Hsla { hue, @@ -186,6 +243,15 @@ impl Color { } /// New `Color` from sRGB colorspace. + /// + /// # Examples + /// + /// ``` + /// # use bevy_render::color::Color; + /// let color = Color::hex("FF00FF").unwrap(); // fuchsia + /// let color = Color::hex("FF00FF7F").unwrap(); // partially transparent fuchsia + /// ``` + /// pub fn hex>(hex: T) -> Result { let hex = hex.as_ref(); @@ -223,6 +289,15 @@ impl Color { } /// New `Color` from sRGB colorspace. + /// + /// # Arguments + /// + /// * `r` - Red channel. [0, 255] + /// * `g` - Green channel. [0, 255] + /// * `b` - Blue channel. [0, 255] + /// + /// See also [`Color::rgb`], [`Color::rgba_u8`], [`Color::hex`]. + /// pub fn rgb_u8(r: u8, g: u8, b: u8) -> Color { Color::rgba_u8(r, g, b, u8::MAX) } @@ -230,6 +305,16 @@ impl Color { // Float operations in const fn are not stable yet // see https://github.com/rust-lang/rust/issues/57241 /// New `Color` from sRGB colorspace. + /// + /// # Arguments + /// + /// * `r` - Red channel. [0, 255] + /// * `g` - Green channel. [0, 255] + /// * `b` - Blue channel. [0, 255] + /// * `a` - Alpha channel. [0, 255] + /// + /// See also [`Color::rgba`], [`Color::rgb_u8`], [`Color::hex`]. + /// pub fn rgba_u8(r: u8, g: u8, b: u8, a: u8) -> Color { Color::rgba( r as f32 / u8::MAX as f32,