Merge #216

216: Add doc alias, doc cleanups, remove trait from Packed struct r=Ogeon a=okaneco

Add "hsb" alias for Hsv
Add "linear" for LinLuma/a and LinSrgb/a
Add "wcag" for RelativeContrast trait
Add "xyY" for Yxy
Add "gray/grey" for Luma
Make rgb::FromHexError public and document it
Clean up document example in RelativeContrast
Remove RgbChannels trait from Packed struct

Co-authored-by: okaneco <47607823+okaneco@users.noreply.github.com>

palette/src/hsv.rs

@@ -42,6 +42,7 @@ pub type Hsva<S = Srgb, T = f32> = Alpha<Hsv<S, T>, T>;
     skip_derives(Rgb, Hsl, Hwb, Hsv)
 )]
 #[repr(C)]
+#[doc(alias = "hsb")]
 pub struct Hsv<S = Srgb, T = f32>
 where
     T: FloatComponent,

palette/src/luma.rs

@@ -13,8 +13,10 @@ pub type SrgbLuma<T = f32> = Luma<Srgb, T>;
 pub type SrgbLumaa<T = f32> = Lumaa<Srgb, T>;
 
 /// Linear luminance.
+#[doc(alias = "linear")]
 pub type LinLuma<Wp = D65, T = f32> = Luma<Linear<Wp>, T>;
 /// Linear luminance with an alpha component.
+#[doc(alias = "linear")]
 pub type LinLumaa<Wp = D65, T = f32> = Lumaa<Linear<Wp>, T>;
 
 /// Gamma 2.2 encoded luminance.

palette/src/luma/luma.rs

@@ -42,6 +42,8 @@ pub type Lumaa<S = Srgb, T = f32> = Alpha<Luma<S, T>, T>;
     skip_derives(Xyz, Yxy, Luma)
 )]
 #[repr(C)]
+#[doc(alias = "gray")]
+#[doc(alias = "grey")]
 pub struct Luma<S = Srgb, T = f32>
 where
     T: Component,

palette/src/relative_contrast.rs

@@ -22,12 +22,15 @@ use crate::{from_f64, FromF64};
 /// ```rust
 /// use std::str::FromStr;
 /// use palette::{Srgb, RelativeContrast};
+/// # fn main() -> Result<(), palette::rgb::FromHexError> {
 ///
 /// // the rustdoc "DARK" theme background and text colors
-/// let my_background_rgb: Srgb<f32> = Srgb::from_str("#353535").unwrap().into_format();
-/// let my_foreground_rgb = Srgb::from_str("#ddd").unwrap().into_format();
+/// let my_background_rgb: Srgb<f32> = Srgb::from(0x353535).into_format();
+/// let my_foreground_rgb = Srgb::from_str("#ddd")?.into_format();
 ///
 /// assert!(my_background_rgb.has_enhanced_contrast_text(&my_foreground_rgb));
+/// # Ok(())
+/// # }
 /// ```
 ///
 /// The possible range of contrast ratios is from 1:1 to 21:1. There is a
@@ -47,7 +50,7 @@ use crate::{from_f64, FromF64};
 /// [Success Criterion 1.4.6 Contrast (Enhanced) (Level AAA)](https://www.w3.org/WAI/WCAG21/Understanding/contrast-enhanced)
 ///
 /// [Success Criterion 1.4.11 Non-text Contrast (Level AA)](https://www.w3.org/WAI/WCAG21/Understanding/non-text-contrast.html)
-
+#[doc(alias = "wcag")]
 pub trait RelativeContrast {
     /// The type of the contrast ratio.
     type Scalar: FromF64 + PartialOrd;

palette/src/rgb.rs

@@ -5,7 +5,7 @@ use crate::white_point::WhitePoint;
 use crate::{Component, FloatComponent, FromComponent, Yxy};
 
 pub use self::packed::{channels, Packed, RgbChannels};
-pub use self::rgb::{Rgb, Rgba};
+pub use self::rgb::{FromHexError, Rgb, Rgba};
 
 mod packed;
 mod rgb;
@@ -16,8 +16,10 @@ pub type Srgb<T = f32> = Rgb<encoding::Srgb, T>;
 pub type Srgba<T = f32> = Rgba<encoding::Srgb, T>;
 
 /// Linear sRGB.
+#[doc(alias = "linear")]
 pub type LinSrgb<T = f32> = Rgb<Linear<encoding::Srgb>, T>;
 /// Linear sRGB with an alpha component.
+#[doc(alias = "linear")]
 pub type LinSrgba<T = f32> = Rgba<Linear<encoding::Srgb>, T>;
 
 /// Gamma 2.2 encoded sRGB.

palette/src/rgb/packed.rs

@@ -12,10 +12,9 @@ use crate::Pixel;
 /// express each value of the Red, Green, Blue, and Alpha components in the
 /// RGBA color.
 ///
-/// Note that conversion from float to integer component types in `palette` maps
-/// the floating point value to the integer's value range and then rounds the
-/// result before casting to the integer type. An example of the difference in
-/// conversion methods is shown below.
+/// Note that conversion from float to integer component types in `palette`
+/// rounds to nearest even: an `Rgb` component of `0.5` will convert to
+/// `0x80`/`128`, not `0x7F`/`127`.
 ///
 /// ```
 /// use approx::assert_relative_eq;
@@ -25,9 +24,9 @@ use crate::Pixel;
 /// let packed: Packed = Srgb::new(0.5, 0.0, 0.5).into_format().into();
 /// assert_eq!(0xFF80_0080, packed.color);
 ///
-/// let unpacked: Srgba<u8> = Packed::<Rgba>::from(0x80FF_FF80).into();
+/// let unpacked: Srgba<u8> = Packed::<Rgba>::from(0xFFFF_FF80).into();
 /// assert_relative_eq!(
-///     Srgba::new(0.5, 1.0, 1.0, 0.5),
+///     Srgba::new(1.0, 1.0, 1.0, 0.5),
 ///     unpacked.into_format(),
 ///     epsilon = 0.01
 /// );
@@ -62,7 +61,7 @@ use crate::Pixel;
 #[derive(Copy, Clone, Debug, PartialEq, Eq, Pixel)]
 #[palette(palette_internal)]
 #[repr(C)]
-pub struct Packed<C: RgbChannels = channels::Argb> {
+pub struct Packed<C = channels::Argb> {
     /// The sRGB color packed into a `u32`.
     pub color: u32,
 

palette/src/rgb/rgb.rs

@@ -1031,9 +1031,12 @@ where
     }
 }
 
+/// Error type for parsing a string of hexadecimal characters to an `Rgb` color.
 #[derive(Debug)]
 pub enum FromHexError {
+    /// An error occurred while parsing the string into a valid integer.
     ParseIntError(ParseIntError),
+    /// The hex value was not in a valid 3 or 6 character format.
     HexFormatError(&'static str),
 }
 

palette/src/yxy.rs

@@ -37,6 +37,7 @@ pub type Yxya<Wp = D65, T = f32> = Alpha<Yxy<Wp, T>, T>;
     skip_derives(Xyz, Yxy, Luma)
 )]
 #[repr(C)]
+#[doc(alias = "xyY")]
 pub struct Yxy<Wp = D65, T = f32>
 where
     T: FloatComponent,