Documentation

src/bext.rs

@@ -3,20 +3,19 @@ pub type LU = f32;
 pub type LUFS = f32;
 pub type Decibels = f32;
 
-/**
- * Broadcast-WAV metadata record.
- * 
- * The `bext` record contains information about the original recording of the 
- * Wave file, including a longish (256 ASCII chars) description field, 
- * originator identification fields, creation calendar date and time, a 
- * sample-accurate recording time field, and a SMPTE UMID. 
- * 
- * For a Wave file to be a complaint "Broadcast-WAV" file, it must contain
- * a `bext` metadata record.
- * 
- * For reference on the structure and use of the BEXT record
- * check out [EBU Tech 3285](https://tech.ebu.ch/docs/tech/tech3285.pdf).
- */
+
+///  Broadcast-WAV metadata record.
+///
+///  The `bext` record contains information about the original recording of the 
+///  Wave file, including a longish (256 ASCII chars) description field, 
+///  originator identification fields, creation calendar date and time, a 
+///  sample-accurate recording time field, and a SMPTE UMID. 
+///
+///  For a Wave file to be a complaint "Broadcast-WAV" file, it must contain
+///  a `bext` metadata record.
+///
+///  For reference on the structure and use of the BEXT record
+///  check out [EBU Tech 3285](https://tech.ebu.ch/docs/tech/tech3285.pdf).
 #[derive(Debug)]
 pub struct Bext {
 
@@ -47,7 +46,6 @@ pub struct Bext {
 
     /// SMPTE 330M UMID
     /// 
-    /// 
     /// This field is `None` if the version is less than 1.
     pub umid: Option<[u8; 64]>,
 

src/common_format.rs

@@ -1,12 +1,5 @@
 use uuid::Uuid;
 
-/**
- * References:
- * - http://www-mmsp.ece.mcgill.ca/Documents/AudioFormats/WAVE/Docs/multichaudP.pdf
-*/
-
-// http://dream.cs.bath.ac.uk/researchdev/wave-ex/bformat.html
-
 const BASIC_PCM: u16        = 0x0001;
 const BASIC_FLOAT: u16      = 0x0003;
 const BASIC_MPEG: u16       = 0x0050;
@@ -45,7 +38,7 @@ fn uuid_from_basic_tag(tag: u16) -> Uuid {
 
 /// Sample format of the Wave file.
 /// 
-///
+/// 
 #[derive(Debug, Copy, Clone, PartialEq)]
 pub enum CommonFormat {
     /// Integer linear PCM
@@ -71,6 +64,7 @@ pub enum CommonFormat {
 }
 
 impl CommonFormat {
+    /// Resolve a tag and Uuid to a `CommonFormat`.
     pub fn make(basic: u16, uuid: Option<Uuid>) -> Self {
         match (basic, uuid) {
             (BASIC_PCM, _) => Self::IntegerPCM,
@@ -85,6 +79,10 @@ impl CommonFormat {
         }
     }
 
+    /// Get the appropriate tag and `Uuid` for the callee.
+    /// 
+    /// If there is no appropriate tag for the format of the callee, the 
+    /// returned tag will be 0xFFFE and the `Uuid` will describe the format.
     pub fn take(self) -> (u16, Uuid) {
         match self {
             Self::IntegerPCM => (BASIC_PCM, UUID_PCM),

src/lib.rs

@@ -124,7 +124,7 @@ mod wavewriter;
 
 pub use errors::Error;
 pub use wavereader::WaveReader;
-pub use wavewriter::WaveWriter;
+pub use wavewriter::{WaveWriter, AudioFrameWriter};
 pub use bext::Bext;
 pub use fmt::{WaveFmt, WaveFmtExtended, ChannelDescriptor, ChannelMask, ADMAudioID};
 pub use common_format::CommonFormat;

src/wavewriter.rs

@@ -10,12 +10,17 @@ use super::chunks::WriteBWaveChunks;
 use byteorder::LittleEndian;
 use byteorder::WriteBytesExt;
 
-
+/// Write audio frames to a `WaveWriter`.
+/// 
+/// 
 pub struct AudioFrameWriter<W> where W: Write + Seek {
     inner : WaveChunkWriter<W>
 }
 
 impl<W> AudioFrameWriter<W> where W: Write + Seek {
+
+    /// Write one audio frame.
+    /// 
     pub fn write_integer_frame(&mut self, buffer: &[i32]) -> Result<u64,Error> {
         let format = self.inner.inner.format;
         assert!(buffer.len() as u16 == format.channel_count, 
@@ -38,12 +43,24 @@ impl<W> AudioFrameWriter<W> where W: Write + Seek {
         Ok(1)
     }
 
+    /// Finish writing audio frames and unwrap the inner `WaveWriter`.
+    /// 
+    /// This method must be called when the client has finished writing audio
+    /// data. This will finalize the audio data chunk.
     pub fn end(self) -> Result<WaveWriter<W>, Error> {
         self.inner.end()
     }
 }
 
-
+/// Write a wave data chunk.
+/// 
+/// `WaveChunkWriter` implements `Write` and can be written to like any 
+/// writeable stream. 
+/// 
+/// ### Important 
+/// 
+/// When you are done writing to a chunk you must call `end()` in order to 
+/// finalize the chunk for storage.
 pub struct WaveChunkWriter<W> where W: Write + Seek {
     inner : WaveWriter<W>,
     content_start_pos : u64,
@@ -165,6 +182,10 @@ impl<W> WaveWriter<W> where W: Write + Seek {
         WaveChunkWriter::begin(self, ident)
     }
 
+    /// Create an audio frame writer, which takes possession of the callee 
+    /// `WaveWriter`.
+    /// 
+    /// 
     pub fn audio_frame_writer(mut self) -> Result<AudioFrameWriter<W>, Error> {
         // append elm1 chunk