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

crates/stackable-operator/crds/DummyCluster.yaml

@@ -17,7 +17,7 @@ spec:
     name: v1alpha1
     schema:
       openAPIV3Schema:
-        description: Auto-generated derived type for DummyClusterSpec via `CustomResource`
+        description: A DummyCluster is a test-only resource used by operator-rs to exercise CRD generation. It is not backed by a real operator.
         properties:
           spec:
             properties:

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/trybuild.rs

@@ -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/CHANGELOG.md

@@ -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, which otherwise defaults to a generic auto-generated
+  string ([#1228]).
+
+[#1228]: https://github.com/stackabletech/operator-rs/pull/1228
+
 ## [0.10.0] - 2026-04-27
 
 ### Added

crates/xtask/src/crd/dummy.rs

@@ -78,6 +78,7 @@ pub mod versioned {
         group = "dummy.stackable.tech",
         kind = "DummyCluster",
         status = "v1alpha1::DummyClusterStatus",
+        doc = "A DummyCluster is a test-only resource used by operator-rs to exercise CRD generation. It is not backed by a real operator.",
         namespaced,
     ))]
     #[derive(Clone, CustomResource, Debug, Deserialize, JsonSchema, PartialEq, Serialize)]