chore: Add doc comments

Author: Techassi

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

@@ -1,6 +1,6 @@
 use std::ops::Not;
 
-use darling::{FromAttributes, Result};
+use darling::{util::IdentString, FromAttributes, Result};
 use proc_macro2::TokenStream;
 use quote::quote;
 use syn::ItemEnum;
@@ -88,14 +88,19 @@ impl Container {
     }
 }
 
+/// A versioned enum.
 pub(crate) struct Enum {
     /// List of variants defined in the original enum. How, and if, an item
     /// should generate code, is decided by the currently generated version.
     pub(crate) variants: Vec<VersionedVariant>,
+
+    /// Common container data which is shared between enums and structs.
     pub(crate) common: CommonContainerData,
 }
 
+// Common token generation
 impl Enum {
+    /// Generates code for the enum definition.
     pub(crate) fn generate_definition(&self, version: &VersionDefinition) -> TokenStream {
         let original_attributes = &self.common.original_attributes;
         let ident = &self.common.idents.original;
@@ -115,6 +120,7 @@ impl Enum {
         }
     }
 
+    /// Generates code for the `From<Version> for NextVersion` implementation.
     pub(crate) fn generate_from_impl(
         &self,
         version: &VersionDefinition,
@@ -133,14 +139,7 @@ impl Enum {
                 let next_version_ident = &next_version.ident;
                 let version_ident = &version.ident;
 
-                let mut variants = TokenStream::new();
-                for variant in &self.variants {
-                    variants.extend(variant.generate_for_from_impl(
-                        version,
-                        next_version,
-                        enum_ident,
-                    ));
-                }
+                let variants = self.generate_from_variants(version, next_version, enum_ident);
 
                 // Include allow(deprecated) only when this or the next version is
                 // deprecated. Also include it, when a variant in this or the next
@@ -172,13 +171,29 @@ impl Enum {
         }
     }
 
+    /// Generates code for enum variants used in `From` implementations.
+    fn generate_from_variants(
+        &self,
+        version: &VersionDefinition,
+        next_version: &VersionDefinition,
+        enum_ident: &IdentString,
+    ) -> TokenStream {
+        let mut tokens = TokenStream::new();
+
+        for variant in &self.variants {
+            tokens.extend(variant.generate_for_from_impl(version, next_version, enum_ident));
+        }
+
+        tokens
+    }
+
     /// Returns whether any variant is deprecated in the provided `version`.
     fn is_any_variant_deprecated(&self, version: &VersionDefinition) -> bool {
-        // First, iterate over all variants. The `any` function will return true if any of the
-        // function invocations return true. If a field doesn't have a chain,
-        // we can safely default to false (unversioned fields cannot be
-        // deprecated). Then we retrieve the status of the field and ensure it
-        // is deprecated.
+        // First, iterate over all variants. The `any` function will return true
+        // if any of the function invocations return true. If a variant doesn't
+        // have a chain, we can safely default to false (unversioned variants
+        // cannot be deprecated). Then we retrieve the status of the variant and
+        // ensure it is deprecated.
         self.variants.iter().any(|f| {
             f.changes.as_ref().map_or(false, |c| {
                 c.value_is(&version.inner, |a| {

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

@@ -15,6 +15,7 @@ use crate::{
 mod r#enum;
 mod r#struct;
 
+/// Contains common container data shared between structs and enums.
 pub(crate) struct CommonContainerData {
     /// Original attributes placed on the container, like `#[derive()]` or `#[cfg()]`.
     pub(crate) original_attributes: Vec<Attribute>,
@@ -26,19 +27,26 @@ pub(crate) struct CommonContainerData {
     pub(crate) idents: ContainerIdents,
 }
 
+/// Supported types of containers, structs and enums.
+///
+/// Abstracting away with kind of container is generated makes it possible to create a list of
+/// containers when the macro is used on modules. This enum provides functions to generate code
+/// which then internally call the appropriate function based on the variant.
 pub(crate) enum Container {
     Struct(Struct),
     Enum(Enum),
 }
 
 impl Container {
+    /// Generates the container definition for the specified `version`.
     pub(crate) fn generate_definition(&self, version: &VersionDefinition) -> TokenStream {
         match self {
             Container::Struct(s) => s.generate_definition(version),
             Container::Enum(e) => e.generate_definition(version),
         }
     }
 
+    /// Generates the container `From<Version> for NextVersion` implementation.
     pub(crate) fn generate_from_impl(
         &self,
         version: &VersionDefinition,
@@ -51,6 +59,16 @@ impl Container {
         }
     }
 
+    /// Generates Kubernetes specific code snippets.
+    ///
+    /// This function returns three values:
+    ///
+    /// - an enum variant ident,
+    /// - an enum variant display string,
+    /// - and a `CustomResource::crd()` call
+    ///
+    /// This function only returns `Some` if it is a struct. Enums cannot be used to define
+    /// Kubernetes custom resources.
     pub(crate) fn generate_kubernetes_item(
         &self,
         version: &VersionDefinition,
@@ -61,6 +79,10 @@ impl Container {
         }
     }
 
+    /// Generates Kubernetes specific code to merge two or more CRDs into one.
+    ///
+    /// This function only returns `Some` if it is a struct. Enums cannot be used to define
+    /// Kubernetes custom resources.
     pub(crate) fn generate_kubernetes_merge_crds(
         &self,
         enum_variant_idents: Vec<IdentString>,
@@ -80,13 +102,20 @@ impl Container {
     }
 }
 
+/// A versioned standalone container.
+///
+/// A standalone container is a container defined outside of a versioned module. See [`Module`][1]
+/// for more information about versioned modules.
+///
+/// [1]: crate::codegen::module::Module
 pub(crate) struct StandaloneContainer {
     versions: Vec<VersionDefinition>,
     container: Container,
     vis: Visibility,
 }
 
 impl StandaloneContainer {
+    /// Creates a new versioned standalone struct.
     pub(crate) fn new_struct(
         item_struct: ItemStruct,
         attributes: StandaloneContainerAttributes,
@@ -103,6 +132,7 @@ impl StandaloneContainer {
         })
     }
 
+    /// Creates a new versioned standalone enum.
     pub(crate) fn new_enum(
         item_enum: ItemEnum,
         attributes: StandaloneContainerAttributes,
@@ -119,6 +149,7 @@ impl StandaloneContainer {
         })
     }
 
+    /// Generate tokens containing every piece of code required for a standalone container.
     pub(crate) fn generate_tokens(&self) -> TokenStream {
         let vis = &self.vis;
 

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

@@ -119,15 +119,19 @@ impl Container {
     }
 }
 
+/// A versioned struct.
 pub(crate) struct Struct {
     /// List of fields defined in the original struct. How, and if, an item
     /// should generate code, is decided by the currently generated version.
     pub(crate) fields: Vec<VersionedField>,
+
+    /// Common container data which is shared between structs and enums.
     pub(crate) common: CommonContainerData,
 }
 
 // Common token generation
 impl Struct {
+    /// Generates code for the struct definition.
     pub(crate) fn generate_definition(&self, version: &VersionDefinition) -> TokenStream {
         let original_attributes = &self.common.original_attributes;
         let ident = &self.common.idents.original;
@@ -151,6 +155,7 @@ impl Struct {
         }
     }
 
+    /// Generates code for the `From<Version> for NextVersion` implementation.
     pub(crate) fn generate_from_impl(
         &self,
         version: &VersionDefinition,
@@ -202,6 +207,7 @@ impl Struct {
         }
     }
 
+    /// Generates code for struct fields used in `From` implementations.
     fn generate_from_fields(
         &self,
         version: &VersionDefinition,
@@ -217,7 +223,13 @@ impl Struct {
         tokens
     }
 
+    /// Returns whether any field is deprecated in the provided `version`.
     fn is_any_field_deprecated(&self, version: &VersionDefinition) -> bool {
+        // First, iterate over all fields. The `any` function will return true
+        // if any of the function invocations return true. If a field doesn't
+        // have a chain, we can safely default to false (unversioned fields
+        // cannot be deprecated). Then we retrieve the status of the field and
+        // ensure it is deprecated.
         self.fields.iter().any(|f| {
             f.changes.as_ref().map_or(false, |c| {
                 c.value_is(&version.inner, |a| {

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

@@ -12,6 +12,10 @@ pub(crate) struct ModuleInput {
     pub(crate) ident: Ident,
 }
 
+/// A versioned module.
+///
+/// Versioned modules allow versioning multiple containers at once without introducing conflicting
+/// version module definitions.
 pub(crate) struct Module {
     versions: Vec<VersionDefinition>,
     containers: Vec<Container>,
@@ -21,6 +25,7 @@ pub(crate) struct Module {
 }
 
 impl Module {
+    /// Creates a new versioned module containing versioned containers.
     pub(crate) fn new(
         ModuleInput { ident, vis, .. }: ModuleInput,
         preserve_module: bool,
@@ -36,6 +41,7 @@ impl Module {
         }
     }
 
+    /// Generates tokens for all versioned containers.
     pub(crate) fn generate_tokens(&self) -> TokenStream {
         if self.containers.is_empty() {
             return quote! {};