feat(versioned): support crd(doc = "...") to override the CRD root description

Author: lfrancke

crates/stackable-versioned-macros/src/attrs/container.rs

@@ -53,6 +53,8 @@ pub struct ContainerSkipArguments {
 /// - `scale`: Configure the scale subresource for horizontal pod autoscaling integration.
 /// - `shortname`: Set a shortname for the CR object. This can be specified multiple
 ///   times.
+/// - `doc`: Override the root description of the generated CRD. If not set, kube
+///   generates a generic one automatically.
 /// - `skip`: Controls skipping parts of the generation.
 #[derive(Clone, Debug, FromMeta)]
 pub struct StructCrdArguments {
@@ -71,7 +73,7 @@ pub struct StructCrdArguments {
     pub shortnames: Vec<String>,
     // category
     // selectable
-    // doc
+    pub doc: Option<String>,
     // annotation
     // label
 }

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

@@ -302,14 +302,20 @@ impl Struct {
             .map(|s| quote! { , shortname = #s })
             .collect();
 
+        let doc = spec_gen_ctx
+            .kubernetes_arguments
+            .doc
+            .as_ref()
+            .map(|d| quote! { , doc = #d });
+
         quote! {
             // The end-developer needs to derive CustomResource and JsonSchema.
             // This is because we don't know if they want to use a re-exported or renamed import.
             #[kube(
                 // These must be comma separated (except the last) as they always exist:
                 group = #group, version = #version, kind = #kind
                 // These fields are optional, and therefore the token stream must prefix each with a comma:
-                #singular #plural #namespaced #crates #status #scale #shortnames
+                #singular #plural #namespaced #crates #status #scale #shortnames #doc
             )]
         }
     }

crates/stackable-versioned-macros/tests/inputs/pass/crd_doc.rs

@@ -0,0 +1,21 @@
+use stackable_versioned::versioned;
+// ---
+#[versioned(version(name = "v1alpha1"))]
+// ---
+pub(crate) mod versioned {
+    #[versioned(crd(
+        group = "stackable.tech",
+        doc = "A FooCluster, deployed and managed by the example operator."
+    ))]
+    #[derive(
+        Clone,
+        Debug,
+        serde::Deserialize,
+        serde::Serialize,
+        schemars::JsonSchema,
+        kube::CustomResource,
+    )]
+    pub(crate) struct FooSpec {}
+}
+// ---
+fn main() {}

crates/stackable-versioned-macros/tests/snapshots/stackable_versioned_macros__snapshots__pass@crd_doc.rs.snap

@@ -24,6 +24,7 @@ mod inputs {
         // mod conversion_tracking;
         // mod crate_overrides;
         // mod crate_overrides_only_kube;
+        // mod crd_doc;
         // mod docs;
         // mod downgrade_with;
         // mod enum_fields;

crates/stackable-versioned-macros/tests/trybuild.rs

@@ -4,6 +4,14 @@ All notable changes to this project will be documented in this file.
 
 ## [Unreleased]
 
+### Added
+
+- Add support to provide a `#[versioned(crd(doc = "..."))]` argument to override the root
+  description of the generated CRD, replacing the default `Auto-generated derived type for
+  <Kind>Spec via `CustomResource`` ([#1228]).
+
+[#1228]: https://github.com/stackabletech/operator-rs/pull/1228
+
 ## [0.10.0] - 2026-04-27
 
 ### Added