Improve documentation.

openh264/src/formats/mod.rs

@@ -1,4 +1,23 @@
 //! Handles conversions, e.g., between RGB and YUV.
+//!
+//! In particular when encoding frames your source data might be a YUV buffer, or one of multiple RGB formats. The structs and
+//! traits in here can help you with that format conversion.
+//!
+//! # Examples
+//!
+//! Load a _vanilla_ 3x8 bytes per pixel RGB slice into a [YUVBuffer]:
+//!
+//! ```rust
+//! use openh264::formats::{RgbSliceU8, YUVBuffer};
+//!
+//! // Assume this is a 2x2 pixel RGB buffer you got from somewhere.
+//! let raw_rgb = &[ 10, 10, 10, 20, 20, 20, 30, 30, 30, 40, 40, 40 ];
+//! let rgb_source = RgbSliceU8::new(raw_rgb, (2, 2));
+//!
+//! // Now you have a YUV which you can feed into the encoder.
+//! let yuv = YUVBuffer::from_rgb_source(rgb_source);
+//! ```
+//!
 
 mod rgb;
 mod yuv;

openh264/src/formats/yuv.rs

@@ -103,10 +103,9 @@ impl YUVBuffer {
 
     /// Allocates a new YUV buffer with the given width and height and data.
     ///
-    /// Data `rgb` format is specified the configured [`RGBSource`] trait.
+    /// # Panics
     ///
-    /// Both dimensions must be even. May panic or yield unexpected results if `rgb`
-    /// does not match the formats given.
+    /// May panic if invoked with an RGB source where the dimensions are not multiples of 2.
     pub fn from_rgb_source<T: RGBSource>(rgb: T) -> Self {
         let mut rval = Self::new(rgb.dimensions().0, rgb.dimensions().1);
         rval.read_rgb(rgb);
@@ -115,9 +114,9 @@ impl YUVBuffer {
 
     /// Reads an RGB buffer, converts it to YUV and stores it.
     ///
-    /// Data `rgb` format is specified the configured [`RGBSource`] trait.
+    /// # Panics
     ///
-    /// May panic or yield unexpected results if `rgb` does not match the formats given.
+    /// May panic if the given `rgb` does not match the internal format.
     pub fn read_rgb<T: RGBSource>(&mut self, rgb: T) {
         // Make sure we only attempt to read sources that match our own size.
         assert_eq!(self.dimensions(), rgb.dimensions());