docs(stackable-versioned): Improve various sections of docs (#966)

* docs: Explain that struct describes latest version

* docs: Explain merged_crd method

* docs: Remove outdated warning about preserve_module

* chore: Update example in README

Author: Techassi

crates/stackable-versioned-macros/src/lib.rs

@@ -29,7 +29,7 @@ mod utils;
 /// example, `#[automatically_derived]` and `#[allow(deprecated)]` are removed
 /// in most examples to reduce visual clutter.
 ///
-/// ## Declaring Versions
+/// <div class="warning">
 ///
 /// It is **important** to note that this macro must be placed before any other
 /// (derive) macros and attributes. Macros supplied before the versioned macro
@@ -38,16 +38,29 @@ mod utils;
 /// attributes are applied to the generated versioned instances of the
 /// container.
 ///
+/// </div>
+///
+/// ## Declaring Versions
+///
 /// Before any of the fields or variants can be versioned, versions need to be
 /// declared at the container level. Each version currently supports two
 /// parameters: `name` and the `deprecated` flag. The `name` must be a valid
 /// (and supported) format.
 ///
 /// <div class="warning">
+///
 /// Currently, only Kubernetes API versions are supported. The macro checks each
 /// declared version and reports any error encountered during parsing.
+///
 /// </div>
 ///
+/// It should be noted that the defined struct always represents the **latest**
+/// version, eg: when defining three versions `v1alpha1`, `v1beta1`, and `v1`,
+/// the struct will describe the structure of the data in `v1`. This behaviour
+/// is especially noticeable in the [`changed()`](#changed-action) action which
+/// works "backwards" by describing how a field looked before the current
+/// (latest) version.
+///
 /// ```
 /// # use stackable_versioned_macros::versioned;
 /// #[versioned(version(name = "v1alpha1"))]
@@ -252,12 +265,6 @@ mod utils;
 /// }
 /// ```
 ///
-/// <div class="warning">
-/// It is planned to move the <code>preserve_module</code> flag into the
-/// <code>options()</code> argument list, but currently seems tricky to
-/// implement.
-/// </div>
-///
 /// ## Item Actions
 ///
 /// This crate currently supports three different item actions. Items can
@@ -601,6 +608,11 @@ println!("{}", serde_yaml::to_string(&merged_crd).unwrap());
 # }
 ```
 
+The generated `merged_crd` method is a wrapper around [kube's `merge_crds`][1]
+function. It automatically calls the `crd` methods of the CRD in all of its
+versions and additionally provides a strongly typed selector for the stored
+API version.
+
 Currently, the following arguments are supported:
 
 - `group`: Set the group of the CR object, usually the domain of the company.

crates/stackable-versioned/README.md

@@ -30,7 +30,7 @@ struct Foo {
     /// My docs
     #[versioned(
         added(since = "v1alpha1"),
-        renamed(since = "v1beta1", from = "gau"),
+        changed(since = "v1beta1", from_name = "gau"),
         deprecated(since = "v2", note = "not required anymore")
     )]
     deprecated_bar: usize,