From 17e05f57f4b95b51196893cd341fdc089f20c6bb Mon Sep 17 00:00:00 2001
From: HampusM <hampus@hampusmat.com>
Date: Mon, 26 Aug 2024 20:59:45 +0200
Subject: docs: add documentation comments

---
 src/lib.rs | 54 ++++++++++++++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 54 insertions(+)

diff --git a/src/lib.rs b/src/lib.rs
index fc92c3a..fefcb97 100644
--- a/src/lib.rs
+++ b/src/lib.rs
@@ -57,6 +57,7 @@ where
         1
     };
 
+    /// Returns a new `MultiVec`. This function does not allocate any memory.
     pub const fn new() -> Self
     {
         Self {
@@ -69,6 +70,12 @@ where
         }
     }
 
+    /// Pushes a item to the `MultiVec`.
+    ///
+    /// ## Note on performance
+    /// Pushing can be pretty slow. Since all of the field lists are stored in the same
+    /// allocation, when pushing and the `MultiVec` needs to grow, all lists except the
+    /// first has to be moved to new locations for them to not overlap.
     pub fn push(&mut self, item: ItemT)
     {
         if self.capacity != 0 {
@@ -90,6 +97,7 @@ where
         self.length = 1;
     }
 
+    /// Returns a field of the item with the given index.
     pub fn get<FieldSel>(
         &self,
         index: usize,
@@ -293,13 +301,58 @@ pub unsafe trait Item
         + DoubleEndedIterator
         + ExactSizeIterator;
 
+    /// The number of fields this item has.
     const FIELD_CNT: usize;
 
+    /// Returns a iterator of metadata of the fields of this item.
     fn iter_field_metadata() -> Self::FieldMetadataIter<'static>;
 
+    /// Drops a field of this item inplace.
+    ///
+    /// # Safety
+    /// Behavior is undefined if any of the following conditions are violated:
+    ///
+    /// * `field_index` must be a valid field index for this item.
+    /// * The value `field_ptr` points to must be valid for the type of the field with
+    ///   index `field_index`.
+    /// * `field_ptr` must be [valid] for both reads and writes.
+    /// * `field_ptr` must be properly aligned, even if the field type has size 0.
+    /// * `field_ptr` must be nonnull, even if the field type has size 0.
+    /// * The value `field_ptr` points to must be valid for dropping, which may mean it
+    ///   must uphold additional invariants. These invariants depend on the type of the
+    ///   value being dropped. For instance, when dropping a Box, the box's pointer to the
+    ///   heap must be valid.
+    /// * While `drop_field_inplace` is executing, the only way to access parts of
+    ///   `field_ptr` is through the `&mut self` references supplied to the [`Drop::drop`]
+    ///   methods that `drop_field_inplace` invokes.
+    ///
+    /// Additionally, if the field type is not [`Copy`], using the pointed-to value after
+    /// calling `drop_field_inplace` can cause undefined behavior. Note that `*field_ptr =
+    /// foo` counts as a use because it will cause the value to be dropped again.
+    ///
+    /// [valid]: https://doc.rust-lang.org/std/ptr/index.html#safety
     unsafe fn drop_field_inplace(field_index: usize, field_ptr: *mut u8);
 }
 
+/// Contains metadata of a field of a [`Item`].
+///
+/// # Examples
+/// ```
+/// # use multi_vec::ItemFieldMetadata;
+/// #
+/// struct CatFood
+/// {
+///     label: String,
+///     age_days: u16,
+///     quality: u8,
+/// }
+///
+/// let cat_food_field_metadata = ItemFieldMetadata {
+///     offset: std::mem::offset_of!(CatFood, age_days),
+///     size: std::mem::size_of::<u16>(),
+///     alignment: std::mem::align_of::<u16>(),
+/// };
+/// ```
 pub struct ItemFieldMetadata
 {
     pub offset: usize,
@@ -320,6 +373,7 @@ where
 
     type Field;
 
+    /// Returns metadata of this item field.
     fn metadata() -> &'static ItemFieldMetadata;
 }
 
-- 
cgit v1.2.3-18-g5258