[WIP]Lib WriteError, Write, Buffer docs

utils/buffer/src/lib.rs

@@ -15,13 +15,19 @@ pub use aes_gcm::aead::Buffer as AeadBuffer;
 pub use buffer_pool::BufferPool;
 pub use slice::Slice;
 
+/// Represents errors that can occur while writing data into a buffer.
 pub enum WriteError {
+    /// No data could be written.
     WriteZero,
 }
 
 pub trait Write {
+    /// Writes data from a byte slice (`buf`) into the buffer, returning the number of bytes
+    /// written.
     fn write(&mut self, buf: &[u8]) -> Result<usize, WriteError>;
 
+    /// Attempts to write the entire byte slice (`buf`) into the buffer, returning an error if all
+    /// the data could not be written.
     fn write_all(&mut self, buf: &[u8]) -> Result<(), WriteError>;
 }
 
@@ -63,27 +69,46 @@ impl Write for &mut [u8] {
 pub trait Buffer {
     type Slice: AsMut<[u8]> + AsRef<[u8]> + Into<Slice>;
 
-    // Caller need to borrow a buffer to write some date
+    // RR TODO
+    //
+    /// Borrows a mutable slice of the buffer, allowing the caller to write data into it. The caller
+    /// specifies the length of the data they need to write.
     fn get_writable(&mut self, len: usize) -> &mut [u8];
 
-    // Caller need to get the previously written buffer and should own it
+    // RR TODO
+    //
+    /// Provides ownership of the buffer data that has already been written.
     fn get_data_owned(&mut self) -> Self::Slice;
 
-    // Caller need a view in the written part of the buffer
+    /// Provides a mutable reference to the written portion of the buffer, up to the specified
+    /// length, without transferring ownership of the buffer. This allows the caller to have a view
+    /// into and modify the buffer's data.
     fn get_data_by_ref(&mut self, len: usize) -> &mut [u8];
 
-    // Caller need a view in the written part of the buffer
+    /// Provides an immutable reference to the written portion of the buffer, up to the specified
+    /// length, without transferring ownership of the buffer. This allows the caller to have a view
+    /// into the buffer's data.
     fn get_data_by_ref_(&self, len: usize) -> &[u8];
 
-    // Return the size of the written part of the buffer that is still owned by the Buffer
+    /// Return the size of the written part of the buffer that is still owned by the Buffer
+    /// Returns the size of the written portion of the buffer. It helps track how much of the
+    /// buffer has been filled with data.
     fn len(&self) -> usize;
 
-    // Set the first element of the buffer to the element at the given index (here only for
-    // perfomnce do not use unless you are really sure about what it do)
+    /// Set the first element of the buffer to the element at the given index (here only for
+    /// performance do not use unless you are really sure about what it do)
+    ///
+    /// Allows the caller to modify the starting point of the buffer, essentially discarding data
+    /// up to the specified index. This is for performance optimization , but its use is considered
+    /// unsafe unless you are sure of the consequences.
     fn danger_set_start(&mut self, index: usize);
 
+    /// Returns `true` if the buffer is empty, `false` otherwise.
     fn is_empty(&self) -> bool {
         self.len() == 0
     }
+
+    /// Determines if the buffer is safe to drop or if it contains essential data that needs to be
+    /// processed.
     fn is_droppable(&self) -> bool;
 }