Updated doucmentation to proper comment style

src/fmt.rs

@@ -5,6 +5,7 @@ use std::io::Cursor;
 use byteorder::LittleEndian;
 use byteorder::WriteBytesExt;
 
+// Need more test cases for ADMAudioID
 #[allow(dead_code)]
 
 /// ADM Audio ID record.

src/wavereader.rs

@@ -69,12 +69,11 @@ pub struct WaveReader<R: Read + Seek> {
 }
 
 impl WaveReader<File> {
-    /**
+    
-     * Open a file for reading.
+     /// Open a file for reading.
-     * 
+     ///
-     * A convenience that opens `path` and calls `Self::new()`
+     /// A convenience that opens `path` and calls `Self::new()`
-     *   
+     
-     */
     pub fn open(path: &str) -> Result<Self, ParserError> {
         let inner = File::open(path)?;
         return Ok( Self::new(inner)? )
@@ -82,48 +81,45 @@ impl WaveReader<File> {
 }
 
 impl<R: Read + Seek> WaveReader<R> {
-    /**
+    
-     * Wrap a `Read` struct in a new `WaveReader`.
+    /// Wrap a `Read` struct in a new `WaveReader`.
-     * 
+    /// 
-     * This is the primary entry point into the `WaveReader` interface. The
+    /// This is the primary entry point into the `WaveReader` interface. The
-     * stream passed as `inner` must be at the beginning of the header of the
+    /// stream passed as `inner` must be at the beginning of the header of the
-     * WAVE data. For a .wav file, this means it must be at the start of the 
+    /// WAVE data. For a .wav file, this means it must be at the start of the 
-     * file.
+    /// file.
-     * 
+    ///
-     * This function does a minimal validation on the provided stream and
+    /// This function does a minimal validation on the provided stream and
-     * will return an `Err(errors::Error)` immediately if there is a structural 
+    /// will return an `Err(errors::Error)` immediately if there is a structural 
-     * inconsistency that makes the stream unreadable or if it's missing 
+    /// inconsistency that makes the stream unreadable or if it's missing 
-     * essential components that make interpreting the audio data impossible.
+    /// essential components that make interpreting the audio data impossible.
-     * 
+     
-     * ```rust
+    /// ```rust
-     * use std::fs::File;
+    /// use std::fs::File;
-     * use std::io::{Error,ErrorKind};
+    /// use std::io::{Error,ErrorKind};
-     * use bwavfile::{WaveReader, Error as WavError};
+    /// use bwavfile::{WaveReader, Error as WavError};
-     * 
+    ///
-     * let f = File::open("tests/media/error.wav").unwrap();
+    /// let f = File::open("tests/media/error.wav").unwrap();
-     * 
+    ///
-     * let reader = WaveReader::new(f);
+    /// let reader = WaveReader::new(f);
-     * 
+    ///
-     * match reader {
+    /// match reader {
-     *      Ok(_) => panic!("error.wav should not be openable"),
+    ///      Ok(_) => panic!("error.wav should not be openable"),
-     *      Err( WavError::IOError( e ) ) => {
+    ///      Err( WavError::IOError( e ) ) => {
-     *          assert_eq!(e.kind(), ErrorKind::UnexpectedEof)
+    ///          assert_eq!(e.kind(), ErrorKind::UnexpectedEof)
-     *      }
+    ///      }
-     *      Err(e) => panic!("Unexpected error was returned {:?}", e)
+    ///      Err(e) => panic!("Unexpected error was returned {:?}", e)
-     * }
+    /// }
-     * 
+    /// 
-     * ```
+    /// ```
-     * 
-    */
     pub fn new(inner: R) -> Result<Self,ParserError> {
         let mut retval = Self { inner };
         retval.validate_readable()?;
         Ok(retval)
     }
 
-    /**
+    
-     * Unwrap the inner reader.
+    /// Unwrap the inner reader.
-     */
     pub fn into_inner(self) -> R {
         return self.inner;
     }
@@ -137,9 +133,8 @@ impl<R: Read + Seek> WaveReader<R> {
         Ok(AudioFrameReader::new(self.inner, format, audio_chunk_reader.0, audio_chunk_reader.1)?)
     }
 
-    /**
+    
-     * The count of audio frames in the file.
+    /// The count of audio frames in the file.
-     */
     pub fn frame_length(&mut self) -> Result<u64, ParserError> {
         let (_, data_length ) = self.get_chunk_extent_at_index(DATA_SIG, 0)?;
         let format = self.format()?;
@@ -155,7 +150,6 @@ impl<R: Read + Seek> WaveReader<R> {
         self.inner.read_wave_fmt()
     }
 
-    ///
     /// The Broadcast-WAV metadata record for this file, if present.
     /// 
     pub fn broadcast_extension(&mut self) -> Result<Option<Bext>, ParserError> {
@@ -285,35 +279,33 @@ impl<R: Read + Seek> WaveReader<R> {
         }
     }
 
-    /** 
+    /// Validate minimal WAVE file.
-     * Validate minimal WAVE file.
+    ///
-     * 
+    /// `Ok(())` if the source is `validate_readable()` AND
-     * `Ok(())` if the source is `validate_readable()` AND
+    ///
-     * 
+    ///   - Contains _only_ a `fmt` chunk and `data` chunk, with no other chunks present
-     *   - Contains _only_ a `fmt` chunk and `data` chunk, with no other chunks present
+    ///   - `fmt` chunk is exactly 16 bytes long and begins _exactly_ at file offset 12
-     *   - `fmt` chunk is exactly 16 bytes long and begins _exactly_ at file offset 12
+    ///   - `data` content begins _exactly_ at file offset 36
-     *   - `data` content begins _exactly_ at file offset 36
+    ///   - is not an RF64/BW64
-     *   - is not an RF64/BW64
+    ///
-     * 
+    /// Some clients require a WAVE file to only contain format and data without any other
-     * 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.
-     * metadata and this function is provided to validate this condition.
+    ///
-     * 
+    /// ### Examples
-     * ### Examples
+    ///
-     * 
+    /// ```
-     * ```
+    /// # use bwavfile::WaveReader;
-     * # use bwavfile::WaveReader;
+    ///
-     * 
+    /// let mut w = WaveReader::open("tests/media/ff_minimal.wav").unwrap();
-     * let mut w = WaveReader::open("tests/media/ff_minimal.wav").unwrap();
+    /// w.validate_minimal().expect("Minimal wav did not validate not minimal!");
-     * w.validate_minimal().expect("Minimal wav did not validate not minimal!");
+    /// ```
-     * ```
+    ///
-     * 
+    /// ```
-     * ```
+    /// # use bwavfile::WaveReader;
-     * # use bwavfile::WaveReader;
+    ///
-     * 
+    /// let mut x = WaveReader::open("tests/media/pt_24bit_51.wav").unwrap();
-     * let mut x = WaveReader::open("tests/media/pt_24bit_51.wav").unwrap();
+    /// x.validate_minimal().expect_err("Complex WAV validated minimal!");
-     * x.validate_minimal().expect_err("Complex WAV validated minimal!");
+    /// ```
-     * ```
-    */
     pub fn validate_minimal(&mut self) -> Result<(), ParserError>  {
         self.validate_readable()?;
 
@@ -327,39 +319,37 @@ impl<R: Read + Seek> WaveReader<R> {
         }
     }
 
-    /**
+    /// Validate Broadcast-WAVE file format
-     * Validate Broadcast-WAVE file format
+    /// 
-     * 
+    /// Returns `Ok(())` if `validate_readable()` and file contains a 
-     * Returns `Ok(())` if `validate_readable()` and file contains a 
+    /// Broadcast-WAV metadata record (a `bext` chunk).
-     * Broadcast-WAV metadata record (a `bext` chunk).
+    /// 
-     * 
+    /// ### Examples
-     * ### Examples
+    /// 
-     * 
+    /// ```
-     * ```
+    /// # use bwavfile::WaveReader;
-     * # use bwavfile::WaveReader;
+    /// 
-     * 
+    /// let mut w = WaveReader::open("tests/media/ff_bwav_stereo.wav").unwrap();
-     * let mut w = WaveReader::open("tests/media/ff_bwav_stereo.wav").unwrap();
+    /// w.validate_broadcast_wave().expect("BWAVE file did not validate BWAVE");
-     * w.validate_broadcast_wave().expect("BWAVE file did not validate BWAVE");
+    /// 
-     * 
+    /// let mut x = WaveReader::open("tests/media/pt_24bit.wav").unwrap();
-     * let mut x = WaveReader::open("tests/media/pt_24bit.wav").unwrap();
+    /// x.validate_broadcast_wave().expect("BWAVE file did not validate BWAVE");
-     * x.validate_broadcast_wave().expect("BWAVE file did not validate BWAVE");
+    /// 
-     * 
+    /// let mut y = WaveReader::open("tests/media/audacity_16bit.wav").unwrap();
-     * let mut y = WaveReader::open("tests/media/audacity_16bit.wav").unwrap();
+    /// y.validate_broadcast_wave().expect_err("Plain WAV file DID validate BWAVE");
-     * y.validate_broadcast_wave().expect_err("Plain WAV file DID validate BWAVE");
+    /// ```
-     * ```
+    ///
-    */
     pub fn validate_broadcast_wave(&mut self) -> Result<(), ParserError> {
         self.validate_readable()?;
         let (_, _) = self.get_chunk_extent_at_index(BEXT_SIG, 0)?;
         Ok(())
     } 
 
-    /**
+    ///
-     * Verify data is aligned to a block boundary.
+    /// Verify data is aligned to a block boundary.
-     * 
+    ///
-     * Returns `Ok(())` if `validate_readable()` and the start of the 
+    /// Returns `Ok(())` if `validate_readable()` and the start of the 
-     * `data` chunk's content begins at 0x4000.
+    /// `data` chunk's content begins at 0x4000.
-    */
     pub fn validate_data_chunk_alignment(&mut self) -> Result<() , ParserError> {
         self.validate_readable()?;
         let (start, _) = self.get_chunk_extent_at_index(DATA_SIG, 0)?;
@@ -370,15 +360,13 @@ impl<R: Read + Seek> WaveReader<R> {
         }
     }
 
-    /**
+    /// Verify audio data can be appended immediately to this file.
-     * Verify audio data can be appended immediately to this file.
+    /// 
-     * 
+    /// Returns `Ok(())` if:
-     * Returns `Ok(())` if:
+    ///  - `validate_readable()`
-     *  - `validate_readable()`
+    ///  - there is a `JUNK` or `FLLR` immediately at the beginning of the chunk 
-     *  - there is a `JUNK` or `FLLR` immediately at the beginning of the chunk 
+    ///    list adequately large enough to be overwritten by a `ds64` (92 bytes)
-     *    list adequately large enough to be overwritten by a `ds64` (92 bytes)
+    ///  - `data` is the final chunk
-     *  - `data` is the final chunk
-    */
     pub fn validate_prepared_for_append(&mut self) -> Result<(), ParserError> {
         self.validate_readable()?;