Add docs

Author: Keats

Cargo.toml

@@ -3,7 +3,7 @@ name = "mmap-bitvec"
 version = "0.4.0"
 authors = ["Roderick Bovee <[email protected]>"]
 autobenches = false
-edition = "2018"
+edition = "2021"
 
 [dependencies]
 memmap2 = "0.5"

benches/benchmark.rs

@@ -63,7 +63,7 @@ fn get_range_simplified(mmap: &MmapMut, size: usize, l: usize) -> BitVecSlice {
 
 fn get_range(mmap: &MmapMut, size: usize, r: Range<usize>) -> BitVecSlice {
     if r.end - r.start > BIT_VEC_SLICE_SIZE as usize {
-        panic!(format!("Range too large (>{})", BIT_VEC_SLICE_SIZE))
+        panic!("Range too large (>{})", BIT_VEC_SLICE_SIZE)
     } else if r.end > size {
         panic!("Range ends outside of BitVec")
     }

src/bitvec.rs

@@ -1,14 +1,20 @@
 use std::ops::Range;
 
+/// A nasic bitvector trait that we implement for mmap
 pub trait BitVector {
+    /// Get the value at bit `i`
     fn get(&self, i: usize) -> bool;
+    /// Set the value at bit `i`
     fn set(&mut self, i: usize, x: bool);
+    /// Returns the size of the bitvector
     fn size(&self) -> usize;
 
+    /// Returns the number of bits sets in the given range
     fn rank(&self, r: Range<usize>) -> usize {
         r.fold(0, |a, x| a + if self.get(x) { 1 } else { 0 })
     }
 
+    /// Returns the position of the n-th bit set
     fn select(&self, n: usize, start: usize) -> Option<usize> {
         let mut bits_left = n;
 
@@ -24,6 +30,7 @@ pub trait BitVector {
         None
     }
 
+    /// Return all the bits in the given range as a u128
     fn get_range(&self, r: Range<usize>) -> u128 {
         if r.end - r.start > 128 {
             panic!("Range too large (>128)")
@@ -42,6 +49,7 @@ pub trait BitVector {
         bvs
     }
 
+    /// Sets all the bits in the given range from the given u128
     fn set_range(&mut self, r: Range<usize>, x: u128) {
         let mut cur = x;
         for i in r.rev() {
@@ -50,6 +58,7 @@ pub trait BitVector {
         }
     }
 
+    /// Sets all the bit in the given range to false
     fn clear_range(&mut self, r: Range<usize>) {
         for i in r.rev() {
             self.set(i, false);
@@ -128,5 +137,3 @@ impl BitVector for Vec<u8> {
         self.len() / 8
     }
 }
-
-// TODO: impl for `bv::BitVec` and `bit-vec::BitVec`?

src/bloom.rs

@@ -7,16 +7,18 @@ use murmurhash3::murmurhash3_x64_128;
 use crate::bitvec::BitVector;
 use crate::mmap_bitvec::MmapBitVec;
 
-// we don't want to use murmurhash3::Murmur3Hasher b/c it makes copies of the
-// bytes to be hashed with every single `hash` call
+/// Newtype for murmur hashing
+/// we don't want to use murmurhash3::Murmur3Hasher b/c it makes copies of the
+/// bytes to be hashed with every single `hash` call
 #[derive(Default)]
 pub struct MurmurHasher(u64, u64);
 
 impl MurmurHasher {
+    #[allow(missing_docs)]
     pub fn new() -> Self {
         MurmurHasher(0, 0)
     }
-
+    #[allow(missing_docs)]
     pub fn values(&self) -> (u64, u64) {
         (self.0, self.1)
     }

src/combinatorial.rs

@@ -27,6 +27,7 @@ static MARKER_TABLES: Lazy<HashMap<u8, Vec<u128>>> = Lazy::new(|| {
     m
 });
 
+/// https://en.wikipedia.org/wiki/Combinatorial_number_system
 pub fn rank(value: usize, k: u8) -> u128 {
     assert!(k > 0 && k < 10, "kappa needs to be less than 10");
     // it's possible this may overflow if value > (128 choose k) or return
@@ -42,6 +43,7 @@ pub fn rank(value: usize, k: u8) -> u128 {
     }
 }
 
+/// https://en.wikipedia.org/wiki/Combinatorial_number_system
 pub fn unrank(marker: u128) -> usize {
     // val = choose(rank(0), 1) + choose(rank(1), 2) + choose(rank(2), 3) + ...
     let mut working_marker = marker;

src/lib.rs

@@ -1,10 +1,16 @@
+#![deny(missing_docs)]
+
 //! mmap-bitvec is a library for using file-backed (via mmap) bit vectors and
 //! includes common convenience functions and a few data structures built atop
 //! the included bit vector implementation.
 
+/// The bitvec trait and some impl for built-in types
 pub mod bitvec;
+/// A simple implementation of a Bloom filter backed by `BitVec`
 pub mod bloom;
+/// Some combinatorial utilities
 pub mod combinatorial;
+/// All the utilities to interact with a mmapped bitvector
 pub mod mmap_bitvec;
 
 #[doc(inline)]

src/mmap_bitvec.rs

@@ -12,11 +12,14 @@ use crate::bitvec::BitVector;
 /// Really annoying we have to mock over both of these rather than memmap
 /// just providing support.
 pub enum CommonMmap {
+    /// A mutable mmap
     MmapMut(MmapMut),
+    /// A read-only mmap
     Mmap(Mmap),
 }
 
 impl CommonMmap {
+    /// Get a non-mutable pointer to the mmap
     #[inline]
     pub fn as_ptr(&self) -> *const u8 {
         match self {
@@ -25,6 +28,7 @@ impl CommonMmap {
         }
     }
 
+    /// Get a mutable pointer to the mmap
     #[inline]
     pub fn as_mut_ptr(&mut self) -> *mut u8 {
         // maybe we should override the original type signature and return
@@ -35,6 +39,7 @@ impl CommonMmap {
         }
     }
 
+    /// Flush to disk. A no-op if the mmap is read-only
     #[inline]
     pub fn flush(&mut self) -> Result<(), io::Error> {
         match self {
@@ -56,7 +61,9 @@ impl CommonMmap {
 /// assert_eq!(bv.get_range(2..12), 0b1001101101);
 /// ```
 pub struct MmapBitVec {
+    /// The mmap we are using, either a mutable or read-only one
     pub mmap: CommonMmap,
+    /// Number of bits in the bitvector
     pub size: usize,
     header: Box<[u8]>,
     is_anon: bool,
@@ -243,7 +250,7 @@ impl MmapBitVec {
         Ok(file_mmap)
     }
 
-    // Returns the header
+    /// Returns the header
     pub fn header(&self) -> &[u8] {
         &self.header
     }