png/lib: Add some documentation

Signed-off-by: caleb <etemesicaleb@gmail.com>

zune-png/src/lib.rs

@@ -1,24 +1,54 @@
 //!A png decoder
 //!
-//! # Using
+//! # Usage
+//!
+//! #### Decode to raw bytes.
+//!
+//! This is a simple decode operation which returns raw
+//! bytes of the image.
+//!
+//! - **Note**: The interpretation of the data varies depending
+//! on the endianness of the source image, for 16 bit depth images
+//! each two bytes represent a single pixel in native endian.
+//! So one should inspect `PngDecoder::get_bit_depth` to get bit depth
+//! of image in order to understand the raw bytes layout.
+//!
+//! A more convenient API is given below, using `decode`
 //!
-//! Below is an example of how to decode images
 //! ```no_run
 //! use zune_png::PngDecoder;
+//! let mut decoder = PngDecoder::new(&[]);
+//!
+//! let pixels = decoder.decode_raw();
+//! ```
+//!
+//! # Decode to u8 or u16 depending on depth
+//!
+//! From above limitation, there are needs to treat result
+//! types differently depending on the image's bit depth.
+//!
+//! That's what the `decode` api for the PngDecoder does.
+//!
+//!```no_run
+//! use zune_png::PngDecoder;
 //! use zune_core::result::DecodingResult;
 //! let mut decoder = PngDecoder::new(&[]);
 //!
 //! let pixels = decoder.decode().unwrap();
-//! let value=match pixels {
-//!
-//!     DecodingResult::U8(value)=>{
-//!         // you got  a u8
-//!     }
-//!     DecodingResult::U16(value)=>{
-//!         // you got a u16, squeeze it to u8?
-//!     }
-//! };
-//! ```
+//!
+//! match pixels {
+//!    DecodingResult::U8(_px)=>{
+//!        // do something with images with 8 bit depths
+//!    }
+//!    DecodingResult::U16(_px)=>{
+//!        // do something with images with 16 bit depths
+//!    }
+//!}
+//!```
+//! The above has a more complicated API, but it ensures that you
+//! handle any image depth correctly.
+//!
+//! E.g one can make it that 16 bit images are scaled to 8 bit images.
 //!
 pub use decoder::PngDecoder;