Merge pull request #34 from noamteyssier/33-improve-documentation-throughout-repo

33 improve documentation throughout repo

Author: noamteyssier

Cargo.toml

@@ -1,6 +1,6 @@
 [package]
 name = "binseq"
-version = "0.5.3"
+version = "0.5.4"
 edition = "2021"
 
 [dependencies]

src/error.rs

@@ -1,47 +1,101 @@
+/// Custom Result type for binseq operations, wrapping the custom [`Error`] type
 pub type Result<T> = std::result::Result<T, Error>;
 
+/// The main error type for the binseq library, encompassing all possible error cases
+/// that can occur during binary sequence operations.
 #[derive(thiserror::Error, Debug)]
 #[error(transparent)]
 pub enum Error {
+    /// Errors related to binary sequence header processing
     HeaderError(#[from] HeaderError),
+    /// Errors that occur during read operations
     ReadError(#[from] ReadError),
+    /// Errors that occur during write operations
     WriteError(#[from] WriteError),
+    /// Standard I/O errors from the Rust standard library
     IoError(#[from] std::io::Error),
+    /// UTF-8 encoding/decoding errors
     Utf8Error(#[from] std::str::Utf8Error),
+    /// Errors from the bitnuc nucleotide processing librar
     BitnucError(#[from] bitnuc::NucleotideError),
+    /// Generic errors that can occur in any part of the system
     AnyhowError(#[from] anyhow::Error),
 }
 
+/// Errors specific to processing and validating binary sequence headers
 #[derive(thiserror::Error, Debug)]
 pub enum HeaderError {
+    /// The magic number in the header does not match the expected value
+    ///
+    /// # Arguments
+    /// * `u32` - The invalid magic number that was found
     #[error("Invalid magic number: {0}")]
     InvalidMagicNumber(u32),
+
+    /// The format version in the header is not supported
+    ///
+    /// # Arguments
+    /// * `u8` - The unsupported version number that was found
     #[error("Invalid format version: {0}")]
     InvalidFormatVersion(u8),
+
+    /// The reserved bytes in the header contain unexpected values
     #[error("Invalid reserved bytes")]
     InvalidReservedBytes,
+
+    /// The size of the data does not match what was specified in the header
+    ///
+    /// # Arguments
+    /// * First `usize` - The actual number of bytes provided
+    /// * Second `usize` - The expected number of bytes according to the header
     #[error("Invalid number of bytes provided: {0}. Expected: {1}")]
     InvalidSize(usize, usize),
 }
 
+/// Errors that can occur while reading binary sequence data
 #[derive(thiserror::Error, Debug)]
 pub enum ReadError {
+    /// The file being read is not a regular file (e.g., it might be a directory or special file)
     #[error("File is not regular")]
     IncompatibleFile,
+
+    /// The file appears to be truncated or corrupted
+    ///
+    /// # Arguments
+    /// * `usize` - The byte position where the truncation was detected
     #[error(
         "Number of bytes in file does not match expectation - possibly truncated at byte pos {0}"
     )]
     FileTruncation(usize),
+
+    /// Attempted to access a record index that is beyond the available range
+    ///
+    /// # Arguments
+    /// * First `usize` - The requested record index
+    /// * Second `usize` - The maximum available record index
     #[error("Requested record index ({0}) is out of record range ({1})")]
     OutOfRange(usize, usize),
 }
 
+/// Errors that can occur while writing binary sequence data
 #[derive(thiserror::Error, Debug)]
 pub enum WriteError {
+    /// The length of the sequence being written does not match what was specified in the header
+    ///
+    /// # Fields
+    /// * `expected` - The sequence length specified in the header
+    /// * `got` - The actual length of the sequence being written
     #[error("Sequence length ({got}) does not match the header ({expected})")]
     UnexpectedSequenceLength { expected: u32, got: usize },
+
+    /// The sequence contains invalid nucleotide characters
+    ///
+    /// # Arguments
+    /// * `String` - Description of the invalid nucleotides found
     #[error("Invalid nucleotides found in sequence: {0}")]
     InvalidNucleotideSequence(String),
+
+    /// Attempted to write data without first setting up the header
     #[error("Missing header in writer builder")]
     MissingHeader,
 }

src/header.rs

@@ -1,17 +1,36 @@
+//! Header module for the binseq library
+//!
+//! This module provides the header structure and functionality for binary sequence files.
+//! The header contains metadata about the binary sequence data, including format version,
+//! sequence length, and other information necessary for proper interpretation of the data.
+
 use byteorder::{ByteOrder, LittleEndian};
 use std::io::{Read, Write};
 
 use crate::{error::Result, HeaderError};
 
-/// Current magic number: "BSEQ" in ASCII
+/// Current magic number: "BSEQ" in ASCII (in little-endian byte order)
+///
+/// This is used to identify binary sequence files and verify file integrity.
 const MAGIC: u32 = 0x51455342;
 
-/// Current format version
+/// Current format version of the binary sequence file format
+///
+/// This version number allows for future format changes while maintaining backward compatibility.
 const FORMAT: u8 = 1;
 
 /// Size of the header in bytes
+///
+/// The header has a fixed size to ensure consistent reading and writing of binary sequence files.
 pub const SIZE_HEADER: usize = 32;
 
+/// Header structure for binary sequence files
+///
+/// The `BinseqHeader` contains metadata about the binary sequence data stored in a file,
+/// including format information, sequence lengths, and space for future extensions.
+///
+/// The total size of this structure is 32 bytes, with a fixed layout to ensure
+/// consistent reading and writing across different platforms.
 #[derive(Debug, Clone, Copy, PartialEq, Eq)]
 pub struct BinseqHeader {
     /// Magic number to identify the file format
@@ -40,6 +59,19 @@ pub struct BinseqHeader {
     pub reserved: [u8; 19],
 }
 impl BinseqHeader {
+    /// Creates a new header with the specified sequence length
+    ///
+    /// This constructor initializes a standard header with the given sequence length,
+    /// setting the magic number and format version to their default values.
+    /// The extended sequence length (xlen) is set to 0.
+    ///
+    /// # Arguments
+    ///
+    /// * `slen` - The length of sequences in the file
+    ///
+    /// # Returns
+    ///
+    /// A new `BinseqHeader` instance
     pub fn new(slen: u32) -> Self {
         Self {
             magic: MAGIC,
@@ -50,6 +82,19 @@ impl BinseqHeader {
         }
     }
 
+    /// Creates a new header with both primary and extended sequence lengths
+    ///
+    /// This constructor initializes a header for files that contain both primary
+    /// and secondary sequence data, such as quality scores or annotations.
+    ///
+    /// # Arguments
+    ///
+    /// * `slen` - The length of primary sequences in the file
+    /// * `xlen` - The length of secondary/extended sequences in the file
+    ///
+    /// # Returns
+    ///
+    /// A new `BinseqHeader` instance with extended sequence information
     pub fn new_extended(slen: u32, xlen: u32) -> Self {
         Self {
             magic: MAGIC,
@@ -60,6 +105,26 @@ impl BinseqHeader {
         }
     }
 
+    /// Parses a header from a fixed-size byte array
+    ///
+    /// This method validates the magic number and format version before constructing
+    /// a header instance. If validation fails, appropriate errors are returned.
+    ///
+    /// # Arguments
+    ///
+    /// * `buffer` - A byte array of exactly `SIZE_HEADER` bytes containing the header data
+    ///
+    /// # Returns
+    ///
+    /// * `Ok(BinseqHeader)` - A valid header parsed from the buffer
+    /// * `Err(Error)` - If the buffer contains invalid header data
+    ///
+    /// # Errors
+    ///
+    /// Returns an error if:
+    /// * The magic number is incorrect
+    /// * The format version is unsupported
+    /// * The reserved bytes are invalid
     pub fn from_bytes(buffer: &[u8; SIZE_HEADER]) -> Result<Self> {
         let magic = LittleEndian::read_u32(&buffer[0..4]);
         if magic != MAGIC {
@@ -84,7 +149,26 @@ impl BinseqHeader {
         })
     }
 
-    /// Parses an arbitrarily sized buffer
+    /// Parses a header from an arbitrarily sized buffer
+    ///
+    /// This method extracts the header from the beginning of a buffer that may be larger
+    /// than the header size. It checks that the buffer is at least as large as the header
+    /// before attempting to parse it.
+    ///
+    /// # Arguments
+    ///
+    /// * `buffer` - A byte slice containing at least `SIZE_HEADER` bytes
+    ///
+    /// # Returns
+    ///
+    /// * `Ok(BinseqHeader)` - A valid header parsed from the buffer
+    /// * `Err(Error)` - If the buffer is too small or contains invalid header data
+    ///
+    /// # Errors
+    ///
+    /// Returns an error if:
+    /// * The buffer is smaller than `SIZE_HEADER`
+    /// * The header data is invalid (see `from_bytes` for validation details)
     pub fn from_buffer(buffer: &[u8]) -> Result<Self> {
         let mut bytes = [0u8; SIZE_HEADER];
         if buffer.len() < SIZE_HEADER {
@@ -94,6 +178,23 @@ impl BinseqHeader {
         Self::from_bytes(&bytes)
     }
 
+    /// Writes the header to a writer
+    ///
+    /// This method serializes the header to its binary representation and writes it
+    /// to the provided writer.
+    ///
+    /// # Arguments
+    ///
+    /// * `writer` - Any type that implements the `Write` trait
+    ///
+    /// # Returns
+    ///
+    /// * `Ok(())` - If the header was successfully written
+    /// * `Err(Error)` - If writing to the writer failed
+    ///
+    /// # Errors
+    ///
+    /// Returns an error if writing to the writer fails (typically an I/O error).
     pub fn write_bytes<W: Write>(&self, writer: &mut W) -> Result<()> {
         let mut buffer = [0u8; SIZE_HEADER];
         LittleEndian::write_u32(&mut buffer[0..4], self.magic);
@@ -105,6 +206,25 @@ impl BinseqHeader {
         Ok(())
     }
 
+    /// Reads a header from a reader
+    ///
+    /// This method reads exactly `SIZE_HEADER` bytes from the provided reader and
+    /// parses them into a header structure.
+    ///
+    /// # Arguments
+    ///
+    /// * `reader` - Any type that implements the `Read` trait
+    ///
+    /// # Returns
+    ///
+    /// * `Ok(BinseqHeader)` - A valid header read from the reader
+    /// * `Err(Error)` - If reading from the reader failed or the header data is invalid
+    ///
+    /// # Errors
+    ///
+    /// Returns an error if:
+    /// * Reading from the reader fails (typically an I/O error)
+    /// * The header data is invalid (see `from_bytes` for validation details)
     pub fn from_reader<R: Read>(reader: &mut R) -> Result<Self> {
         let mut buffer = [0u8; SIZE_HEADER];
         reader.read_exact(&mut buffer)?;

src/lib.rs

@@ -1,3 +1,46 @@
+#![doc = include_str!("../README.md")]
+//!
+//! # Overview
+//!
+//! The `binseq` library provides efficient tools for working with binary-encoded
+//! nucleotide sequences. It offers:
+//!
+//! - Compact 2-bit encoding of nucleotide sequences
+//! - Memory-mapped file access for efficient reading
+//! - Parallel processing capabilities
+//! - Configurable policies for handling invalid nucleotides
+//! - Support for both single and paired-end sequences
+//!
+//! # Core Components
+//!
+//! - [`BinseqWriter`]: Writes sequences to binary format
+//! - [`MmapReader`]: Reads sequences using memory mapping
+//! - [`BinseqHeader`]: Defines file format and sequence lengths
+//! - [`Policy`]: Configures invalid nucleotide handling
+//! - [`ParallelProcessor`]: Enables parallel sequence processing
+//!
+//! # Example
+//!
+//! ```
+//! use binseq::{BinseqHeader, BinseqWriterBuilder, MmapReader, Policy, Result};
+//! use std::io::Cursor;
+//!
+//! fn main() -> Result<()> {
+//!     // Create a writer for sequences of length 100
+//!     let header = BinseqHeader::new(100);
+//!
+//!     let mut writer = BinseqWriterBuilder::default()
+//!         .header(header)
+//!         .build(Cursor::new(Vec::new()))?;
+//!
+//!     // Write a sequence
+//!     let sequence = b"ACGT".repeat(25); // 100 nucleotides
+//!     writer.write_nucleotides(0, &sequence)?;
+//!
+//!     Ok(())
+//! }
+//! ```
+
 #![allow(clippy::module_inception)]
 
 pub mod error;
@@ -14,7 +57,7 @@ pub use parallel::ParallelProcessor;
 pub use policy::{Policy, RNG_SEED};
 pub use reader::{MmapReader, RefRecord};
 pub use utils::expected_file_size;
-pub use writer::{BinseqWriter, BinseqWriterBuilder};
+pub use writer::{BinseqWriter, BinseqWriterBuilder, Encoder};
 
 // #[cfg(test)]
 // mod testing {