From 28b927245669feccd75d119d8e22f8dadc71c293 Mon Sep 17 00:00:00 2001 From: Jamie Hardt Date: Fri, 1 Jan 2021 12:09:26 -0800 Subject: [PATCH] Updated doucmentation to proper comment style --- src/fmt.rs | 1 + src/wavereader.rs | 210 ++++++++++++++++++++++------------------------ 2 files changed, 100 insertions(+), 111 deletions(-) diff --git a/src/fmt.rs b/src/fmt.rs index db1fc43..6d0040e 100644 --- a/src/fmt.rs +++ b/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. diff --git a/src/wavereader.rs b/src/wavereader.rs index 4849ca2..5e85411 100644 --- a/src/wavereader.rs +++ b/src/wavereader.rs @@ -69,12 +69,11 @@ pub struct WaveReader { } impl WaveReader { - /** - * Open a file for reading. - * - * A convenience that opens `path` and calls `Self::new()` - * - */ + + /// Open a file for reading. + /// + /// A convenience that opens `path` and calls `Self::new()` + pub fn open(path: &str) -> Result { let inner = File::open(path)?; return Ok( Self::new(inner)? ) @@ -82,48 +81,45 @@ impl WaveReader { } impl WaveReader { - /** - * Wrap a `Read` struct in a new `WaveReader`. - * - * 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 - * WAVE data. For a .wav file, this means it must be at the start of the - * file. - * - * This function does a minimal validation on the provided stream and - * 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 impossible. - * - * ```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) - * } - * - * ``` - * - */ + + /// Wrap a `Read` struct in a new `WaveReader`. + /// + /// 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 + /// WAVE data. For a .wav file, this means it must be at the start of the + /// file. + /// + /// This function does a minimal validation on the provided stream and + /// 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 impossible. + + /// ```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 { 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 WaveReader { 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 { let (_, data_length ) = self.get_chunk_extent_at_index(DATA_SIG, 0)?; let format = self.format()?; @@ -155,7 +150,6 @@ impl WaveReader { self.inner.read_wave_fmt() } - /// /// The Broadcast-WAV metadata record for this file, if present. /// pub fn broadcast_extension(&mut self) -> Result, ParserError> { @@ -285,35 +279,33 @@ impl WaveReader { } } - /** - * Validate minimal WAVE file. - * - * `Ok(())` if the source is `validate_readable()` AND - * - * - 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 - * - `data` content begins _exactly_ at file offset 36 - * - is not an RF64/BW64 - * - * 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. - * - * ### Examples - * - * ``` - * # 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!"); - * ``` - */ + /// Validate minimal WAVE file. + /// + /// `Ok(())` if the source is `validate_readable()` AND + /// + /// - 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 + /// - `data` content begins _exactly_ at file offset 36 + /// - is not an RF64/BW64 + /// + /// 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. + /// + /// ### Examples + /// + /// ``` + /// # 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()?; @@ -327,39 +319,37 @@ impl WaveReader { } } - /** - * Validate Broadcast-WAVE file format - * - * Returns `Ok(())` if `validate_readable()` and file contains a - * Broadcast-WAV metadata record (a `bext` chunk). - * - * ### Examples - * - * ``` - * # 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"); - * ``` - */ + /// Validate Broadcast-WAVE file format + /// + /// Returns `Ok(())` if `validate_readable()` and file contains a + /// Broadcast-WAV metadata record (a `bext` chunk). + /// + /// ### Examples + /// + /// ``` + /// # 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()?; let (_, _) = self.get_chunk_extent_at_index(BEXT_SIG, 0)?; Ok(()) } - /** - * Verify data is aligned to a block boundary. - * - * Returns `Ok(())` if `validate_readable()` and the start of the - * `data` chunk's content begins at 0x4000. - */ + /// + /// Verify data is aligned to a block boundary. + /// + /// Returns `Ok(())` if `validate_readable()` and the start of the + /// `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 WaveReader { } } - /** - * Verify audio data can be appended immediately to this file. - * - * Returns `Ok(())` if: - * - `validate_readable()` - * - 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) - * - `data` is the final chunk - */ + /// Verify audio data can be appended immediately to this file. + /// + /// Returns `Ok(())` if: + /// - `validate_readable()` + /// - 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) + /// - `data` is the final chunk pub fn validate_prepared_for_append(&mut self) -> Result<(), ParserError> { self.validate_readable()?;