refactor: Centralize doc comment handling

Author: Techassi

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

@@ -1,8 +1,8 @@
 use std::collections::BTreeMap;
 
 use k8s_version::Version;
-use proc_macro2::Span;
-use quote::format_ident;
+use proc_macro2::{Span, TokenStream};
+use quote::{format_ident, quote, ToTokens};
 use syn::Ident;
 
 use crate::{
@@ -34,24 +34,7 @@ pub(crate) struct ContainerVersion {
     pub(crate) ident: Ident,
 
     /// Store additional doc-comment lines for this version.
-    pub(crate) version_specific_docs: Vec<String>,
-}
-
-/// Converts lines of doc-comments into a trimmed list.
-fn process_docs(input: &Option<String>) -> Vec<String> {
-    if let Some(input) = input {
-        input
-            // Trim the leading and trailing whitespace, deleting suprefluous
-            // empty lines.
-            .trim()
-            .lines()
-            // Trim the leading and trailing whitespace on each line that can be
-            // introduced when the developer indents multi-line comments.
-            .map(|line| line.trim().to_owned())
-            .collect()
-    } else {
-        Vec::new()
-    }
+    pub(crate) docs: Docs,
 }
 
 impl From<&ContainerAttributes> for Vec<ContainerVersion> {
@@ -63,13 +46,55 @@ impl From<&ContainerAttributes> for Vec<ContainerVersion> {
                 skip_from: v.skip.as_ref().map_or(false, |s| s.from.is_present()),
                 ident: Ident::new(&v.name.to_string(), Span::call_site()),
                 deprecated: v.deprecated.is_present(),
+                docs: v.doc.clone().into(),
                 inner: v.name,
-                version_specific_docs: process_docs(&v.doc),
             })
             .collect()
     }
 }
 
+#[derive(Clone, Debug)]
+pub(crate) struct Docs(Vec<String>);
+
+impl From<Option<String>> for Docs {
+    fn from(doc: Option<String>) -> Self {
+        let lines = if let Some(doc) = doc {
+            doc
+                // Trim the leading and trailing whitespace, deleting
+                // superfluous empty lines.
+                .trim()
+                .lines()
+                // Trim the leading and trailing whitespace on each line that
+                // can be introduced when the developer indents multi-line
+                // comments.
+                .map(|line| line.trim().into())
+                .collect()
+        } else {
+            Vec::new()
+        };
+
+        Self(lines)
+    }
+}
+
+impl ToTokens for Docs {
+    fn to_tokens(&self, tokens: &mut TokenStream) {
+        for (index, line) in self.0.iter().enumerate() {
+            if index == 0 {
+                // Prepend an empty line to clearly separate the version/action
+                // specific docs.
+                tokens.extend(quote! {
+                    #[doc = ""]
+                })
+            }
+
+            tokens.extend(quote! {
+                #[doc = #line]
+            })
+        }
+    }
+}
+
 /// Removes the deprecated prefix from a field ident.
 ///
 /// See [`DEPRECATED_FIELD_PREFIX`].

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

@@ -106,25 +106,23 @@ impl VersionedEnum {
         // enable the attribute macro to be applied to a module which
         // generates versioned versions of all contained containers.
 
+        let version_specific_docs = &version.docs;
         let version_ident = &version.ident;
 
         let deprecated_note = format!("Version {version} is deprecated", version = version_ident);
         let deprecated_attr = version
             .deprecated
             .then_some(quote! {#[deprecated = #deprecated_note]});
 
-        // Generate doc comments for the container (enum)
-        let version_specific_docs = self.generate_enum_docs(version);
-
         // Generate tokens for the module and the contained enum
         token_stream.extend(quote! {
             #[automatically_derived]
             #deprecated_attr
             #visibility mod #version_ident {
                 use super::*;
 
-                #version_specific_docs
                 #(#original_attributes)*
+                #version_specific_docs
                 pub enum #enum_name {
                     #variants
                 }
@@ -139,26 +137,6 @@ impl VersionedEnum {
         token_stream
     }
 
-    /// Generates version specific doc comments for the enum.
-    fn generate_enum_docs(&self, version: &ContainerVersion) -> TokenStream {
-        let mut tokens = TokenStream::new();
-
-        for (i, doc) in version.version_specific_docs.iter().enumerate() {
-            if i == 0 {
-                // Prepend an empty line to clearly separate the version
-                // specific docs.
-                tokens.extend(quote! {
-                    #[doc = ""]
-                })
-            }
-            tokens.extend(quote! {
-                #[doc = #doc]
-            })
-        }
-
-        tokens
-    }
-
     fn generate_enum_variants(&self, version: &ContainerVersion) -> TokenStream {
         let mut token_stream = TokenStream::new();
 

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

@@ -126,16 +126,14 @@ impl VersionedStruct {
         // enable the attribute macro to be applied to a module which
         // generates versioned versions of all contained containers.
 
+        let version_specific_docs = &version.docs;
         let version_ident = &version.ident;
 
         let deprecated_note = format!("Version {version} is deprecated", version = version_ident);
         let deprecated_attr = version
             .deprecated
             .then_some(quote! {#[deprecated = #deprecated_note]});
 
-        // Generate doc comments for the container (struct)
-        let version_specific_docs = self.generate_struct_docs(version);
-
         // Generate K8s specific code
         let kubernetes_cr_derive = self.generate_kubernetes_cr_derive(version);
 
@@ -146,8 +144,8 @@ impl VersionedStruct {
             #visibility mod #version_ident {
                 use super::*;
 
-                #version_specific_docs
                 #(#original_attributes)*
+                #version_specific_docs
                 #kubernetes_cr_derive
                 pub struct #struct_name {
                     #fields
@@ -163,26 +161,6 @@ impl VersionedStruct {
         token_stream
     }
 
-    /// Generates version specific doc comments for the struct.
-    fn generate_struct_docs(&self, version: &ContainerVersion) -> TokenStream {
-        let mut tokens = TokenStream::new();
-
-        for (i, doc) in version.version_specific_docs.iter().enumerate() {
-            if i == 0 {
-                // Prepend an empty line to clearly separate the version
-                // specific docs.
-                tokens.extend(quote! {
-                    #[doc = ""]
-                })
-            }
-            tokens.extend(quote! {
-                #[doc = #doc]
-            })
-        }
-
-        tokens
-    }
-
     /// Generates struct fields following the `name: type` format which includes
     /// a trailing comma.
     fn generate_struct_fields(&self, version: &ContainerVersion) -> TokenStream {