doc improvements

src/legacy/internal/convert/mod.rs

@@ -9,7 +9,7 @@ use core::{mem, slice};
 /// See also `FromSlice`
 pub trait AsPixels<PixelType> {
     /// Reinterpret the slice as a read-only/shared slice of pixels.
-    /// Multiple consecutive elements in the slice are intepreted as a single pixel
+    /// Multiple consecutive elements in the slice are interpreted as a single pixel
     /// (depending on format, e.g. 3 for RGB, 4 for RGBA).
     ///
     /// Leftover elements are ignored if the slice isn't evenly divisible into pixels.
@@ -18,7 +18,7 @@ pub trait AsPixels<PixelType> {
     /// See also `FromSlice`.
     fn as_pixels(&self) -> &[PixelType];
     /// Reinterpret the slice as a mutable/exclusive slice of pixels.
-    /// Multiple consecutive elements in the slice are intepreted as a single pixel
+    /// Multiple consecutive elements in the slice are interpreted as a single pixel
     /// (depending on format, e.g. 3 for RGB, 4 for RGBA).
     ///
     /// Leftover elements are ignored if the slice isn't evenly divisible into pixels.

src/legacy/internal/pixel.rs

@@ -45,7 +45,7 @@ pub trait ComponentBytes<T: ::bytemuck::Pod> {
 pub trait ColorComponentMap<DestPixel, SrcComponent, DestComponent> {
     /// Convenience function for applying the same formula to every rgb/gray component, but skipping the alpha component.
     ///
-    /// Note that it returns the pixel directly, not an Interator.
+    /// Note that it returns the pixel directly, not an Iterator.
     fn map_c<Callback>(&self, f: Callback) -> DestPixel
         where Callback: FnMut(SrcComponent) -> DestComponent;
 }

src/pixel_traits/has_alpha.rs

@@ -6,11 +6,15 @@ use crate::{Abgr, Argb, Bgra, GrayA, Rgba};
 /// This trait is implemented only for those types in the crate that
 /// contain an alpha component, such as [`Rgba`].
 ///
-/// There are no geneirc methods for dropping of the alpha component,
+/// There are no trait methods for dropping of the alpha component,
 /// because doing that correctly requires alpha-blending of the
-/// color components with some background color. Otherwise
+/// color components with some background color. Otherwise,
 /// meaningless garbage values of the RGB channels of fully-transparent
-/// pixels may be uncovered.
+/// pixels may be uncovered. For example, removing the alpha channel
+/// from Rgba { r: 255, g: 0, b: 0, a: 100 } would result in `Rgb {r:
+/// 255, g: 0, b: 0}` which is very red when you might want to use a white
+/// background color blended with the original color which would end
+/// up being much lighter.
 pub trait HasAlpha: HetPixel {
     /// Returns a copy of the pixel's alpha component.
     ///
@@ -33,7 +37,8 @@ pub trait HasAlpha: HetPixel {
     /// assert_eq!(HasAlpha::alpha(&rgba), 0);
     /// ```
     fn alpha(&self) -> Self::AlphaComponent;
-    /// Returns a mutable borrow of the pixel's alpha component.
+
+    /// Returns a mutable reference of the pixel's alpha component.
     ///
     /// # Examples
     /// ```

src/pixel_traits/het_pixel.rs

@@ -65,7 +65,7 @@ pub trait HetPixel: Copy {
     /// [`Rgba`] has `ColorArray<U> = [U; 3]` also.
     type ColorArray<U>: ArrayLike<U>;
 
-    /// Returns an owned array of copies of the pixels color components.
+    /// Returns an owned array of copies of the pixel's color components.
     ///
     /// # Examples
     ///
@@ -104,7 +104,7 @@ pub trait HetPixel: Copy {
     #[doc(alias = "rgb_mut")]
     fn color_array_mut(&mut self) -> Self::ColorArray<&mut Self::ColorComponent>;
 
-    /// Returns a copy of the pixel's alpha alpha component if it has one.
+    /// Returns a copy of the pixel's alpha component if it has one.
     ///
     /// # Examples
     ///
@@ -121,7 +121,7 @@ pub trait HetPixel: Copy {
     #[doc(alias = "try_alpha")]
     #[doc(alias = "alpha_checked")]
     fn alpha_opt(&self) -> Option<Self::AlphaComponent>;
-    /// Returns a mutable borrow of the pixel's alpha alpha component if it has one.
+    /// Returns a mutable reference of the pixel's alpha component if it has one.
     ///
     /// # Examples
     ///
@@ -171,7 +171,7 @@ pub trait HetPixel: Copy {
         alpha: Self::AlphaComponent,
     ) -> Result<Self, TryFromColorsAlphaError>;
 
-    /// Maps each of the pixels color components with a function `f` to any other type.
+    /// Maps each of the pixel's color components with a function `f` to any other type.
     ///
     /// See [`HetPixel::map_colors_same()`] if you want to map the color components to the
     /// same type.
@@ -199,7 +199,7 @@ pub trait HetPixel: Copy {
     ) -> Self::SelfType<U, Self::AlphaComponent>
     where
         U: Copy + 'static;
-    /// Maps each of the pixels color components with a function `f` to the same type.
+    /// Maps each of the pixel's color components with a function `f` to the same type.
     ///
     /// See [`HetPixel::map_colors()`] if you want to map the color components to a
     /// different type.
@@ -221,7 +221,7 @@ pub trait HetPixel: Copy {
     /// ```
     fn map_colors_same(&self, f: impl FnMut(Self::ColorComponent) -> Self::ColorComponent) -> Self;
 
-    /// Maps the pixels alpha component with a function `f` to any other type.
+    /// Maps the pixel's alpha component with a function `f` to any other type.
     ///
     /// If the pixel has no alpha component then the pixel is returned unchanged.
     ///
@@ -249,7 +249,7 @@ pub trait HetPixel: Copy {
     ) -> Self::SelfType<Self::ColorComponent, U>
     where
         U: Copy + 'static;
-    /// Maps the pixels alpha component with a function `f` to the same type.
+    /// Maps the pixel's alpha component with a function `f` to the same type.
     ///
     /// If the pixel has no alpha component then the pixel is returned unchanged.
     ///

src/pixel_traits/pixel.rs

@@ -36,7 +36,7 @@ pub trait Pixel:
     /// [`Rgba`] has `ComponentArray<U> = [U; 4]`.
     type ComponentArray<U>: ArrayLike<U>;
 
-    /// Returns an owned array of copies of the pixels components.
+    /// Returns an owned array of copies of the pixel's components.
     ///
     /// # Examples
     ///
@@ -56,11 +56,40 @@ pub trait Pixel:
     where
         Self::ComponentArray<Self::Component>: Copy;
 
-    /// Cast `self` to array reference of the pixel's components
+    /// Casts a reference of the pixel to an array reference of the pixel's
+    /// components.
+    ///
+    /// # Examples
+    ///
+    /// ```
+    /// use rgb::{Pixel, Rgb, Rgba};
+    ///
+    /// let rgb = Rgb {r: 0_u8, g: 10, b: 100};
+    /// let rgba = Rgba {r: 0_u8, g: 10, b: 100, a: 50};
+    ///
+    /// assert_eq!(rgb.as_array(), &[0, 10, 100]);
+    /// assert_eq!(rgba.as_array(), &[0, 10, 100, 50]);
+    /// ```
     #[doc(alias = "as_ref")]
     fn as_array(&self) -> &Self::ComponentArray<Self::Component>;
 
-    /// Cast `self` to array reference of the pixel's components
+    /// Casts a mutable reference of the pixel to an mutable array reference of the pixel's
+    /// components.
+    ///
+    /// # Examples
+    ///
+    /// ```
+    /// use rgb::{Pixel, Rgb, Rgba};
+    ///
+    /// let mut rgb = Rgb {r: 0_u8, g: 10, b: 100};
+    /// let mut rgba = Rgba {r: 0_u8, g: 10, b: 100, a: 50};
+    ///
+    /// *rgb.as_array_mut()[1] = 40;
+    /// *rgba.as_array_mut()[2] = 40;
+    ///
+    /// assert_eq!(rgb.as_array(), &[0, 40, 100]);
+    /// assert_eq!(rgba.as_array(), &[0, 10, 40, 50]);
+    /// ```
     #[doc(alias = "as_mut")]
     fn as_array_mut(&mut self) -> &mut Self::ComponentArray<Self::Component>;
 
@@ -106,7 +135,7 @@ pub trait Pixel:
         components: impl IntoIterator<Item = Self::Component>,
     ) -> Result<Self, TryFromComponentsError>;
 
-    /// Maps each of the pixels components with a function `f` to any other component type.
+    /// Maps each of the pixel's components with a function `f` to any other component type.
     ///
     /// See [`Pixel::map_same()`] if you want to map the components to the
     /// same type.
@@ -128,7 +157,7 @@ pub trait Pixel:
     /// ```
     fn map<U>(&self, f: impl FnMut(Self::Component) -> U) -> Self::SelfType<U, U> where U: Copy;
 
-    /// Maps each of the pixels components with a function `f` to the same component type.
+    /// Maps each of the pixel's components with a function `f` to the same component type.
     ///
     /// See [`Pixel::map()`] if you want to map the components to a
     /// different type.