Add documentation to the public structs and functions.

src/reader.rs

@@ -154,6 +154,15 @@ fn parse_block(input: &[u8]) -> IResult<&[u8], BlockType> {
     }
 }
 
+/// Parses a Creative Voice File (VOC) from the given input and returns a `Voc` struct.
+///
+/// # Arguments
+///
+/// * `input` - The byte slice containing the VOC data to parse.
+///
+/// # Returns
+///
+/// Returns a `nom::IResult` containing the remaining input (if any) and the parsed `Voc` struct.
 pub fn parse_voc(input: &[u8]) -> IResult<&[u8], Voc> {
     let (input, _) = tag(SIGNATURE1)(input)?;
     let (input, _) = tag(SIGNATURE2)(input)?;

src/types.rs

@@ -1,73 +1,136 @@
+/// The first signature of a Creative Voice file.
 pub const SIGNATURE1: &str = "Creative Voice File";
+
+/// The second signature of a Creative Voice file, represented as an array of three bytes.
+/// The first two bytes are 0x1A and the third byte is 0x0.
 pub const SIGNATURE2: [u8; 3] = [0x1A, 0x1A, 0x0];
 
-#[derive(Debug)]
+/// Represents a file in the Creative Voice format (.voc).
 pub struct Voc {
+    /// The version of the file format used.
     pub version: Version,
+    /// The checksum value used to validate the integrity of the file data.
     pub checksum: Checksum,
+    /// The data blocks contained in the file.
     pub blocks: Vec<BlockType>,
 }
 
-#[derive(Debug)]
+/// Represents a version number with a major and minor component.
+///
+/// # Notes
+///
+/// The most usual versions are 1.10 and 1.20.
 pub struct Version {
+    /// The major version number.
     pub major: u8,
+    /// The minor version number.
     pub minor: u8,
 }
 
-#[derive(Debug)]
+/// Represents the checksum value used to validate the integrity of the Version.
+///
+/// # Notes
+/// The checksum value is calculated by taking the two-byte little-endian representation of the
+/// file version number (e.g. "0x0a01"), bitwise inverting it, adding the value "0x1234", and
+/// finally truncating the result to 16 bits (i.e. keeping only the lowest 16 bits) to produce
+/// the final checksum value. For example, if the file version is "0x0a01", the checksum value
+/// would be "0x2911".
 pub struct Checksum {
+    /// The value of the checksum.
     pub value: u16,
+    /// Whether the checksum is valid or not.
     pub valid: bool,
 }
 
+/// Represents the codec formats.
+///
+/// # Notes
+///
+/// The `Adpcm4to16` codec is only allowed in a `SoundDataNew`.
 #[derive(Eq, Debug, PartialEq)]
 pub enum Codec {
+    /// PCM 8-bit unsigned format.
     Pcm8BitUnsigned,
+    /// ADPCM 4-bit to 8-bit format.
     Adpcm4to8,
+    /// ADPCM 3-bit to 8-bit format.
     Adpcm3to8,
+    /// ADPCM 2-bit to 8-bit format.
     Adpcm2to8,
+    /// PCM 16-bit signed format.
     Pcm16BitSigned,
+    /// A-law format.
     Alaw,
+    /// u-law format.
     Ulaw,
+    /// ADPCM 4-bit to 16-bit format.
     Adpcm4to16,
 }
-
-#[derive(Eq, Debug, PartialEq)]
+/// Represents the different types of blocks in a VOC file.
+#[derive(Eq, PartialEq)]
 pub enum BlockType {
+    /// Indicates the end of the sound data.
     Terminator,
+    /// Contains sound data.
     SoundData {
+        /// The sample rate of the sound data.
         sample_rate: u32,
+        /// The codec used to encode the sound data.
         codec: Codec,
+        /// The sound data.
         data: Vec<u8>,
     },
+    /// Contains continuation of the sound data.
     SoundDataContinuation {
+        /// The sound data.
         data: Vec<u8>,
     },
+    /// Contains silence.
     Silence {
+        /// The length of the silence in samples.
         length: u16,
+        /// The sample rate of the silence.
         sample_rate: u32,
     },
+    /// A marker with a specific value.
     Marker {
+        /// The value of the marker.
         value: u16,
     },
+    /// Contains text data.
     Text {
+        /// The text data.
         data: Vec<u8>,
     },
+    /// Indicates the start of a repeat block.
     RepeatStart {
+        /// The number of times to repeat the block.
         count: u16,
     },
+    /// Indicates the end of a repeat block.
     RepeatEnd,
+    /// Contains extra information about the sound data.
     ExtraInformation {
+        /// The sample rate of the sound data.
         sample_rate: u32,
+        /// The codec used to encode the sound data.
         codec: Codec,
+        /// The number of channels in the sound data.
         channels: u8,
     },
+    /// Contains sound data with additional information.
     SoundDataNew {
+        /// The sample rate of the sound data.
         sample_rate: u32,
+        /// The number of bits per sample in the sound data.
         bits: u8,
+        /// The number of channels in the sound data.
         channels: u8,
+        /// The codec used to encode the sound data.
         codec: Codec,
+        /// Reserved for future use.
         reserved: u32,
+        /// The sound data.
         data: Vec<u8>,
     },
 }

src/writer.rs

@@ -180,6 +180,15 @@ fn write_block(block: &BlockType) -> Vec<u8> {
     }
 }
 
+/// Writes a `Voc` structure to a byte vector.
+///
+/// # Arguments
+///
+/// * `voc` - A reference to a `Voc` structure to write to bytes.
+///
+/// # Returns
+///
+/// A vector of bytes representing the `Voc` structure.
 pub fn write_voc(voc: &Voc) -> Vec<u8> {
     let mut bytes: Vec<u8> = Vec::new();
     // Signature 1