Added much documentation

src/audio_frame_reader.rs

@@ -34,7 +34,7 @@ impl<R: Read + Seek> AudioFrameReader<R> {
         vec![0i32; self.format.channel_count as usize]
     }
 
-    pub fn read_integer_frame(&mut self, buffer:&mut [i32]) -> Result<(),Error> {
+    pub fn read_integer_frame(&mut self, buffer:&mut [i32]) -> Result<u64,Error> {
         assert!(buffer.len() as u16 == self.format.channel_count, 
             "read_integer_frame was called with a mis-sized buffer, expected {}, was {}", 
             self.format.channel_count, buffer.len());
@@ -52,7 +52,7 @@ impl<R: Read + Seek> AudioFrameReader<R> {
             }
         }
 
-        Ok( () )
+        Ok( 1 )
     }
 }
 

src/lib.rs

@@ -1,6 +1,17 @@
 extern crate encoding;
 extern crate byteorder;
 
+/**!
+ * bwavfile
+ * 
+ * Rust Wave File Reader/Writer with Broadcast-WAV, MBWF and RF64 Support
+ * 
+ * This crate is currently a work-in-progress (I'm using it to teach myself
+ * rust) so the interface may change dramatically and not all features work.
+ * 
+ !*/
+
+
 mod parser;
 mod fourcc;
 mod errors;

src/validation.rs

@@ -1,11 +1,10 @@
 use super::parser::{Parser};
 use super::fourcc::{FourCC, FMT__SIG,DATA_SIG, BEXT_SIG, JUNK_SIG, FLLR_SIG};
 use super::errors::Error as ParserError;
-use super::wavereader::WaveReader;
+use super::wavereader::{WaveReader};
 
 use std::io::{Read,Seek};
 
-
 impl<R:Read + Seek> WaveReader<R> {
     /**
     *  Returns without `Err` if the source meets the minimum standard of 
@@ -34,6 +33,20 @@ impl<R:Read + Seek> WaveReader<R> {
      * 
      * Some clients require a WAVE file to only contain format and data without any other
      * metadata and this function is provided to validate this condition.
+     * 
+     * ```
+     * # use bwavfile::WaveReader;
+     * 
+     * let mut w = WaveReader::open("tests/media/ff_minimal.wav").unwrap();
+     * w.validate_minimal().expect("Minimal wav did not validate not minimal!");
+     * ```
+     * 
+     * ```
+     * # use bwavfile::WaveReader;
+     * 
+     * let mut x = WaveReader::open("tests/media/pt_24bit_51.wav").unwrap();
+     * x.validate_minimal().expect_err("Complex WAV validated minimal!");
+     * ```
     */
     pub fn validate_minimal(&mut self) -> Result<(), ParserError>  {
         self.validate_readable()?;
@@ -53,6 +66,19 @@ impl<R:Read + Seek> WaveReader<R> {
      * 
      * Returns without `Err` if `validate_readable()` and file contains a 
      * Broadcast-WAV metadata record (a `bext` chunk).
+     * 
+     * ```
+     * # use bwavfile::WaveReader;
+     * 
+     * let mut w = WaveReader::open("tests/media/ff_bwav_stereo.wav").unwrap();
+     * w.validate_broadcast_wave().expect("BWAVE file did not validate BWAVE");
+     * 
+     * let mut x = WaveReader::open("tests/media/pt_24bit.wav").unwrap();
+     * x.validate_broadcast_wave().expect("BWAVE file did not validate BWAVE");
+     * 
+     * let mut y = WaveReader::open("tests/media/audacity_16bit.wav").unwrap();
+     * y.validate_broadcast_wave().expect_err("Plain WAV file DID validate BWAVE");
+     * ```
     */
     pub fn validate_broadcast_wave(&mut self) -> Result<(), ParserError> {
         self.validate_readable()?;

src/wavereader.rs

@@ -9,14 +9,30 @@ use super::chunks::{WaveFmt, Bext};
 use super::audio_frame_reader::AudioFrameReader;
 use super::chunks::ReadBWaveChunks;
 //use super::validation;
-use std::io::SeekFrom::{Start};
+//use std::io::SeekFrom::{Start};
 use std::io::{Read, Seek};
 
 
 /**
  * Wave, Broadcast-WAV and RF64/BW64 parser/reader.
  * 
-
+ * ```
+ * use bwavfile::WaveReader;
+ * let mut r = WaveReader::open("tests/media/ff_silence.wav").unwrap();
+ * 
+ * let format = r.format().unwrap();
+ * assert_eq!(format.sample_rate, 44100);
+ * assert_eq!(format.channel_count, 1);
+ * 
+ * let mut frame_reader = r.audio_frame_reader().unwrap();
+ * let mut buffer = frame_reader.create_frame_buffer();
+ * 
+ * let read = frame_reader.read_integer_frame(&mut buffer).unwrap();
+ * 
+ * assert_eq!(buffer, [0i32]);
+ * assert_eq!(read, 1);
+ * 
+ * ```
 */
 #[derive(Debug)]
 pub struct WaveReader<R: Read + Seek> {
@@ -28,6 +44,7 @@ impl WaveReader<File> {
      * Open a file for reading.
      * 
      * A convenience that opens `path` and calls `Self::new()`
+     *   
      */
     pub fn open(path: &str) -> Result<Self, ParserError> {
         let inner = File::open(path)?;
@@ -48,6 +65,26 @@ impl<R: Read + Seek> WaveReader<R> {
      * will return an `Err(errors::Error)` immediately if there is a structural 
      * inconsistency that makes the stream unreadable or if it's missing 
      * essential components that make interpreting the audio data impoossible.
+     * 
+     * ```rust
+     * use std::fs::File;
+     * use std::io::{Error,ErrorKind};
+     * use bwavfile::{WaveReader, Error as WavError};
+     * 
+     * let f = File::open("tests/media/error.wav").unwrap();
+     * 
+     * let reader = WaveReader::new(f);
+     * 
+     * match reader {
+     *      Ok(_) => panic!("error.wav should not be openable"),
+     *      Err( WavError::IOError( e ) ) => {
+     *          assert_eq!(e.kind(), ErrorKind::UnexpectedEof)
+     *      }
+     *      Err(e) => panic!("Unexpected error was returned {:?}", e)
+     * }
+     * 
+     * ```
+     * 
     */
     pub fn new(inner: R) -> Result<Self,ParserError> {
         let mut retval = Self { inner };
@@ -56,7 +93,7 @@ impl<R: Read + Seek> WaveReader<R> {
     }
 
     /**
-     * Unwrap and reliqnish ownership of the inner reader.
+     * Unwrap the inner reader.
      */
     pub fn into_inner(self) -> R {
         return self.inner;