docs: Add doc and developer comments

Author: Techassi

crates/stackable-versioned-macros/src/codegen/chain.rs

@@ -14,6 +14,15 @@ impl<K, V> Neighbors<K, V> for BTreeMap<K, V>
 where
     K: Ord + Eq,
 {
+    /// Returns the values of keys which are neighbors of `key`.
+    ///
+    /// Imagine a map which contains the following keys: 1, 3, 5. Calling this
+    /// function with these keys, results in the following return values:
+    ///
+    /// - Key **0**: `(None, Some(1))`
+    /// - Key **2**: `(Some(1), Some(3))`
+    /// - Key **4**: `(Some(3), Some(5))`
+    /// - Key **6**: `(Some(5), None)`
     fn get_neighbors(&self, key: &K) -> (Option<&V>, Option<&V>) {
         // NOTE (@Techassi): These functions might get added to the standard
         // library at some point. If that's the case, we can use the ones

crates/stackable-versioned-macros/src/codegen/common/container.rs

@@ -5,10 +5,22 @@ use syn::Ident;
 
 use crate::{attrs::common::ContainerAttributes, codegen::common::ContainerVersion};
 
+/// This trait helps to unify versioned containers, like structs and enums.
+///
+/// This trait is implemented by wrapper structs, which wrap the generic
+/// [`VersionedContainer`] struct. The generic type parameter `D` describes the
+/// kind of data, like [`DataStruct`](syn::DataStruct) in case of a struct and
+/// [`DataEnum`](syn::DataEnum) in case of an enum.
+/// The type parameter `I` describes the type of the versioned items, like
+/// [`VersionedField`][1] and [`VersionedVariant`][2].
+///
+/// [1]: crate::codegen::vstruct::field::VersionedField
+/// [2]: crate::codegen::venum::variant::VersionedVariant
 pub(crate) trait Container<D, I>
 where
     Self: Sized + Deref<Target = VersionedContainer<I>>,
 {
+    /// Creates a new versioned container.
     fn new(ident: Ident, data: D, attributes: ContainerAttributes) -> syn::Result<Self>;
 
     /// This generates the complete code for a single versioned container.

crates/stackable-versioned-macros/src/codegen/common/item.rs

@@ -43,16 +43,40 @@ where
     fn get_ident(&self, version: &ContainerVersion) -> Option<&Ident>;
 }
 
+/// This trait enables access to the ident of named items, like fields and
+/// variants.
+///
+/// It additionally provides a function to retrieve the cleaned ident, which
+/// removes the deprecation prefixes.
 pub(crate) trait Named {
     fn cleaned_ident(&self) -> Ident;
     fn ident(&self) -> &Ident;
 }
 
+/// This trait enables access to the common attributes across field and variant
+/// attributes.
 pub(crate) trait Attributes {
     fn common_attrs_owned(self) -> ItemAttributes;
     fn common_attrs(&self) -> &ItemAttributes;
 }
 
+/// This struct combines common common code for versioned fields and variants.
+///
+/// Most of the initial creation of a versioned field and variant are identical.
+/// Currently, the following steps are unified:
+///
+/// - Initial creation of the action chain based on item attributes.
+/// - Insertion of container versions into the chain.
+///
+/// The generic type parameter `I` describes the type of the versioned item,
+/// usually [`Field`](syn::Field) or [`Variant`](syn::Variant). The parameter
+/// `A` indicates the type of item attributes, usually [`FieldAttributes`][1] or
+/// [`VariantAttributes`][2] depending on the used item type. As this type is
+/// only needed during creation of [`Self`](VersionedItem), we must use a
+/// [`PhantomData`] marker.
+///
+/// [1]: crate::attrs::field::FieldAttributes
+/// [2]: crate::attrs::variant::VariantAttributes
 #[derive(Debug)]
 pub(crate) struct VersionedItem<I, A>
 where
@@ -71,6 +95,11 @@ where
     I: Named + Spanned,
 {
     fn new(item: I, container_attrs: &ContainerAttributes) -> syn::Result<Self> {
+        // We use the TryFrom trait here, because the type parameter `A` can use
+        // it as a trait bound. Internally this then calls either `from_field`
+        // for field attributes or `from_variant` for variant attributes. Sadly
+        // darling doesn't provide a "generic" trait which abstracts over the
+        // different `from_` functions.
         let attrs = A::try_from(&item)?;
         attrs.validate_versions(container_attrs, &item)?;
 

crates/stackable-versioned-macros/src/codegen/common/mod.rs

@@ -16,6 +16,7 @@ mod item;
 pub(crate) use container::*;
 pub(crate) use item::*;
 
+/// Type alias to make the type of the version chain easier to handle.
 pub(crate) type VersionChain = BTreeMap<Version, ItemStatus>;
 
 #[derive(Debug, Clone)]
@@ -53,15 +54,22 @@ pub(crate) fn format_container_from_ident(ident: &Ident) -> Ident {
     format_ident!("__sv_{ident}", ident = ident.to_string().to_lowercase())
 }
 
-/// Removes the deprecated prefix from field ident.
+/// Removes the deprecated prefix from a field ident.
+///
+/// See [`DEPRECATED_FIELD_PREFIX`].
 pub(crate) fn remove_deprecated_field_prefix(ident: &Ident) -> Ident {
     remove_ident_prefix(ident, DEPRECATED_FIELD_PREFIX)
 }
 
+/// Removes the deprecated prefix from a variant ident.
+///
+/// See [`DEPRECATED_VARIANT_PREFIX`].
 pub(crate) fn remove_deprecated_variant_prefix(ident: &Ident) -> Ident {
     remove_ident_prefix(ident, DEPRECATED_VARIANT_PREFIX)
 }
 
+/// Removes the provided prefix from an ident and returns the newly created
+/// ident.
 pub(crate) fn remove_ident_prefix(ident: &Ident, prefix: &str) -> Ident {
     format_ident!("{}", ident.to_string().trim_start_matches(prefix))
 }

crates/stackable-versioned-macros/src/codegen/venum/mod.rs

@@ -20,7 +20,7 @@ pub(crate) mod variant;
 /// Stores individual versions of a single enum. Each version tracks variant
 /// actions, which describe if the variant was added, renamed or deprecated in
 /// that version. Variants which are not versioned, are included in every
-/// version of the struct.
+/// version of the enum.
 #[derive(Debug)]
 pub(crate) struct VersionedEnum(VersionedContainer<VersionedVariant>);
 
@@ -61,7 +61,7 @@ impl Container<DataEnum, VersionedVariant> for VersionedEnum {
             if !items.iter().map(|f| f.get_ident(version)).all_unique() {
                 return Err(Error::new(
                     ident.span(),
-                    format!("struct contains renamed fields which collide with other fields in version {version}", version = version.inner),
+                    format!("Enum contains renamed variants which collide with other variants in version {version}", version = version.inner),
                 ));
             }
         }
@@ -115,7 +115,7 @@ impl VersionedEnum {
             .deprecated
             .then_some(quote! {#[deprecated = #deprecated_note]});
 
-        // Generate tokens for the module and the contained struct
+        // Generate tokens for the module and the contained enum
         token_stream.extend(quote! {
             #[automatically_derived]
             #deprecated_attr

crates/stackable-versioned-macros/src/codegen/venum/variant.rs

@@ -19,6 +19,12 @@ use crate::{
     },
 };
 
+/// A versioned variant, which contains contains common [`Variant`] data and a
+/// chain of actions.
+///
+/// The chain of action maps versions to an action and the appropriate variant
+/// name. Additionally, the [`Variant`] data can be used to forward attributes,
+/// generate documentation, etc.
 #[derive(Debug)]
 pub(crate) struct VersionedVariant(VersionedItem<Variant, VariantAttributes>);
 
@@ -56,20 +62,19 @@ impl Attributes for VariantAttributes {
 
 impl Named for Variant {
     fn cleaned_ident(&self) -> Ident {
-        let ident = self.ident();
-        remove_deprecated_variant_prefix(ident)
+        remove_deprecated_variant_prefix(self.ident())
     }
 
     fn ident(&self) -> &Ident {
         &self.ident
     }
 }
 
-// TODO (@Techassi): Figure out a way to be able to only write the following code
-// once for both a versioned field and variant, because the are practically
-// identical.
-
 impl VersionedVariant {
+    /// Creates a new versioned variant.
+    ///
+    /// Internally this calls [`VersionedItem::new`] to handle most of the
+    /// common creation code.
     pub(crate) fn new(
         variant: Variant,
         container_attributes: &ContainerAttributes,
@@ -78,15 +83,19 @@ impl VersionedVariant {
         Ok(Self(item))
     }
 
+    /// Generates tokens to be used in a container definition.
     pub(crate) fn generate_for_container(
         &self,
         container_version: &ContainerVersion,
     ) -> Option<TokenStream> {
         match &self.chain {
-            Some(chain) => match chain
-                .get(&container_version.inner)
-                .expect("internal error: chain must contain container version")
-            {
+            // NOTE (@Techassi): https://rust-lang.github.io/rust-clippy/master/index.html#/expect_fun_call
+            Some(chain) => match chain.get(&container_version.inner).unwrap_or_else(|| {
+                panic!(
+                    "internal error: chain must contain container version {}",
+                    container_version.inner
+                )
+            }) {
                 ItemStatus::Added { ident, .. } => Some(quote! {
                     #ident,
                 }),
@@ -115,6 +124,7 @@ impl VersionedVariant {
         }
     }
 
+    /// Generates tokens to be used in a [`From`] implementation.
     pub(crate) fn generate_for_from_impl(
         &self,
         module_name: &Ident,
@@ -151,14 +161,4 @@ impl VersionedVariant {
             }
         }
     }
-
-    pub(crate) fn get_ident(&self, version: &ContainerVersion) -> Option<&syn::Ident> {
-        match &self.chain {
-            Some(chain) => chain
-                .get(&version.inner)
-                .expect("internal error: chain must contain container version")
-                .get_ident(),
-            None => Some(&self.inner.ident),
-        }
-    }
 }

crates/stackable-versioned-macros/src/codegen/vstruct/field.rs

@@ -71,6 +71,10 @@ impl Named for Field {
 }
 
 impl VersionedField {
+    /// Creates a new versioned field.
+    ///
+    /// Internally this calls [`VersionedItem::new`] to handle most of the
+    /// common creation code.
     pub(crate) fn new(
         field: Field,
         container_attributes: &ContainerAttributes,
@@ -79,6 +83,7 @@ impl VersionedField {
         Ok(Self(item))
     }
 
+    /// Generates tokens to be used in a container definition.
     pub(crate) fn generate_for_container(
         &self,
         container_version: &ContainerVersion,
@@ -95,10 +100,13 @@ impl VersionedField {
 
                 let field_type = &self.inner.ty;
 
-                match chain
-                    .get(&container_version.inner)
-                    .expect("internal error: chain must contain container version")
-                {
+                // NOTE (@Techassi): https://rust-lang.github.io/rust-clippy/master/index.html#/expect_fun_call
+                match chain.get(&container_version.inner).unwrap_or_else(|| {
+                    panic!(
+                        "internal error: chain must contain container version {}",
+                        container_version.inner
+                    )
+                }) {
                     ItemStatus::Added { ident, .. } => Some(quote! {
                         pub #ident: #field_type,
                     }),
@@ -133,6 +141,7 @@ impl VersionedField {
         }
     }
 
+    /// Generates tokens to be used in a [`From`] implementation.
     pub(crate) fn generate_for_from_impl(
         &self,
         version: &ContainerVersion,