Add public docs to the main color structs (#19)

src/hsl.rs

@@ -1,27 +1,32 @@
 use crate::{CreationError, LinearRgb};
 
-/// HSL Color Space: Hue, Saturation, Lightness.
+/// Contains an HSL image.
 ///
-/// The Y channel in YUV only has a loose correlation
-/// with human-perceived brightness.
-/// The L channel in this space is the closest
-/// to a pure measure of human-perceived brightness.
+/// HSL stands for Hue, Saturation and Lightness. It represents pixels in a way that is closer
+/// to human perception than RGB or YUV values.
 ///
-/// An L value of 0.0 is always black, and an L value
-/// of 1.0 is always white. Values in between gradiate
-/// as one would expect. Therefore, this is extremely
-/// useful for applications of measuring perceptual
-/// brightness.
+/// The Y channel in YUV only has a loose correlation with human-perceived brightness.
+/// The L channel in HSL is the closest to a pure measure of human-perceived brightness.
+///
+/// An L value of 0.0 is always black, and an L value of 1.0 is always white. Values in between
+/// gradiate as one would expect. Therefore, this is extremely useful for applications of measuring
+/// perceptual brightness.
+///
+/// Unlike the other structs using [`f32`] as pixel components, the components in this structure do
+/// not exclusively lie in the range [0, 1]. The first (H) component lies in the range [0, 360] and
+/// represents the number of degrees on the cylindrical coordinate system.
 #[derive(Debug, Clone)]
 pub struct Hsl {
-    /// H is a value between 0 and 360 (degrees).
-    /// S and L are values betwen 0.0 and 1.0.
+    // H is a value between 0 and 360 (degrees).
+    // S and L are values betwen 0.0 and 1.0.
     data: Vec<[f32; 3]>,
     width: usize,
     height: usize,
 }
 
 impl Hsl {
+    /// Create a new [`Hsl`] with the given data, width and height.
+    ///
     /// # Errors
     /// - If data length does not match `width * height`
     pub fn new(data: Vec<[f32; 3]>, width: usize, height: usize) -> Result<Self, CreationError> {

src/lib.rs

@@ -5,6 +5,7 @@
 #![allow(clippy::inline_always)]
 #![allow(clippy::module_name_repetitions)]
 #![allow(clippy::similar_names)]
+#![allow(clippy::doc_markdown)]
 #![warn(clippy::clone_on_ref_ptr)]
 #![warn(clippy::create_dir)]
 #![warn(clippy::dbg_macro)]

src/linear_rgb.rs

@@ -7,6 +7,13 @@ use crate::{
     ConversionError, CreationError, Hsl, Rgb, Xyb, Yuv,
 };
 
+/// Contains an RGB image in a linearized color space.
+///
+/// The image is stored as pixels made of three 32-bit floating-point RGB components which are
+/// considered to be in an unspecified linearized color space.
+///
+/// This structure is useful for conversions from gamma-encoded RGB color spaces into other spaces
+/// or representations like [`Hsl`] and [`Xyb`].
 #[derive(Debug, Clone)]
 pub struct LinearRgb {
     data: Vec<[f32; 3]>,
@@ -15,6 +22,8 @@ pub struct LinearRgb {
 }
 
 impl LinearRgb {
+    /// Create a new [`LinearRgb`] with the given data, width and height.
+    ///
     /// # Errors
     /// - If data length does not match `width * height`
     pub fn new(data: Vec<[f32; 3]>, width: usize, height: usize) -> Result<Self, CreationError> {

src/rgb.rs

@@ -6,6 +6,10 @@ use crate::{
     ConversionError, CreationError, LinearRgb, Xyb, Yuv,
 };
 
+/// Contains an RGB image.
+///
+/// The image is stored as pixels made of three 32-bit floating-point RGB components which are
+/// converted from/to linear color space by the specified transfer functions and color primaries.
 #[derive(Debug, Clone)]
 pub struct Rgb {
     data: Vec<[f32; 3]>,
@@ -16,6 +20,11 @@ pub struct Rgb {
 }
 
 impl Rgb {
+    /// Create a new [`Rgb`] with the given data and configuration.
+    ///
+    /// It is up to the caller to ensure that the transfer characteristics and
+    /// color primaries are correct for the data.
+    ///
     /// # Errors
     /// - If data length does not match `width * height`
     pub fn new(
@@ -118,7 +127,6 @@ impl<T: Pixel> TryFrom<&Yuv<T>> for Rgb {
     }
 }
 
-// From XYB
 impl TryFrom<(Xyb, TransferCharacteristic, ColorPrimaries)> for Rgb {
     type Error = ConversionError;
 

src/xyb.rs

@@ -2,6 +2,14 @@ use v_frame::prelude::Pixel;
 
 use crate::{rgb_xyb::linear_rgb_to_xyb, ConversionError, CreationError, LinearRgb, Rgb, Yuv};
 
+/// Contains an XYB image.
+///
+/// XYB is a color space derived from the LMS color space. Instead of representing pixels as some
+/// combination of color components, LMS instead represents the sensitivity of the three cone types
+/// (long, medium, short) in the human eye for a given color.
+///
+/// XYB stores these LMS values in a slightly different way to optimize the perceived quality per
+/// amount of data. This representation is useful to emulate the human perception of colors.
 #[derive(Debug, Clone)]
 pub struct Xyb {
     data: Vec<[f32; 3]>,
@@ -10,6 +18,8 @@ pub struct Xyb {
 }
 
 impl Xyb {
+    /// Create a new [`Xyb`] with the given data, width and height.
+    ///
     /// # Errors
     /// - If data length does not match `width * height`
     pub fn new(data: Vec<[f32; 3]>, width: usize, height: usize) -> Result<Self, CreationError> {

src/yuv.rs

@@ -6,12 +6,24 @@ use v_frame::{frame::Frame, plane::Plane, prelude::Pixel};
 
 use crate::{yuv_rgb::rgb_to_yuv, ConversionError, LinearRgb, Rgb, Xyb};
 
+/// Contains a YCbCr image in a color space defined by [`YuvConfig`].
+///
+/// YCbCr (often called YUV) representations of images are transformed from a "true" RGB image.
+/// These transformations are dependent on the original RGB color space and use one luminance (Y)
+/// as well as two chrominance (U, V) components to represent a color.
+///
+/// The data in this structure supports chroma subsampling (e.g. 4:2:0), multiple bit depths,
+/// and limited range support.
 #[derive(Debug, Clone)]
 pub struct Yuv<T: Pixel> {
     data: Frame<T>,
     config: YuvConfig,
 }
 
+/// Contains the configuration data for a YCbCr image.
+///
+/// This includes color space information, bit depth, chroma subsampling and whether the data
+/// is full or limited range.
 #[derive(Debug, Clone, Copy, PartialEq, Eq)]
 pub struct YuvConfig {
     pub bit_depth: u8,
@@ -58,6 +70,8 @@ pub enum YuvError {
 }
 
 impl<T: Pixel> Yuv<T> {
+    /// Create a new [`Yuv`] with the given data and configuration.
+    ///
     /// # Errors
     /// - If luma plane length does not match `width * height`
     /// - If chroma plane lengths do not match `(width * height) >>