docs: safety comments

Author: robjtede

Cargo.toml

@@ -19,3 +19,6 @@ pin-project-lite = "0.2"
 rust_2018_idioms = "deny"
 missing_debug_implementations = { level = "deny", priority = -1 }
 # missing_docs = { level = "deny", priority = -1 }
+
+[workspace.lints.clippy]
+undocumented_unsafe_blocks = "deny"

crates/compression-core/src/util.rs

@@ -18,7 +18,7 @@ impl<B: AsRef<[u8]>> PartialBuffer<B> {
         &self.buffer.as_ref()[..self.index]
     }
 
-    /// Convenient method for `.writen().len()`
+    /// Convenience method for `.written().len()`.
     pub fn written_len(&self) -> usize {
         self.index
     }
@@ -75,14 +75,11 @@ impl<B: AsRef<[u8]> + AsMut<[u8]>> From<B> for PartialBuffer<B> {
 
 /// Write buffer for compression-codecs.
 ///
-/// Currently it only supports initialized buffer, but will support uninitialized
-/// buffer soon.
-///
 /// # Layout
 ///
 /// ```text
-/// |                                       buffer                                    |
-/// | written and initialized | unwritten but initialized | unwritten and uninitialized
+/// |                                       buffer                                      |
+/// | written and initialized | unwritten but initialized | unwritten and uninitialized |
 /// ```
 #[derive(Debug)]
 pub struct WriteBuffer<'a> {
@@ -110,6 +107,7 @@ impl<'a> WriteBuffer<'a> {
         }
     }
 
+    /// Returns entire buffer capacity, including space which is not yet initialized.
     pub fn capacity(&self) -> usize {
         self.buffer.len()
     }
@@ -118,17 +116,23 @@ impl<'a> WriteBuffer<'a> {
         self.buffer.as_mut_ptr() as *mut _
     }
 
+    /// Returns size of buffer's initialized portion.
+    ///
+    /// This will always be at least [`written_len`](Self::written_len).
     pub fn initialized_len(&self) -> usize {
         self.initialized
     }
 
     pub fn written(&self) -> &[u8] {
         debug_assert!(self.index <= self.initialized);
 
+        // SAFETY: slice up to `index` is always initialized
         unsafe { &*(&self.buffer[..self.index] as *const _ as *const [u8]) }
     }
 
-    /// Convenient method for `.writen().len()`
+    /// Returns size of buffer's written portion.
+    ///
+    /// This will always be at most [`initialized_len`](Self::initialized_len).
     pub fn written_len(&self) -> usize {
         self.index
     }
@@ -148,6 +152,7 @@ impl<'a> WriteBuffer<'a> {
             });
         self.initialized = self.buffer.len();
 
+        // SAFETY: slice up to `index` is always initialized
         unsafe { &mut *(&mut self.buffer[self.index..] as *mut _ as *mut [u8]) }
     }