docs: Add action specific docs, add K8s docs

Author: Techassi

crates/stackable-versioned-macros/Cargo.toml

@@ -6,6 +6,10 @@ license.workspace = true
 edition.workspace = true
 repository.workspace = true
 
+# Enable all features to ensure content appears in the online documentation.
+[package.metadata."docs.rs"]
+all-features = true
+
 # cargo-udeps throws an error that these dependencies are unused. They are,
 # however, used in K8s specific test cases. This is a false-positive and an
 # apparent limitation of cargo-udeps. These entries can be removed once

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

@@ -139,16 +139,19 @@ mod consts;
 ///
 /// ### Added Action
 ///
-/// This action indicates that a item is added in a particular version.
+/// This action indicates that an item is added in a particular version.
 /// Available parameters are:
 ///
 /// - `since` to indicate since which version the item is present.
-/// - `default_fn` to customize the default function used to populate the item
+/// - `default` to customize the default function used to populate the item
 ///   in auto-generated [`From`] implementations.
 ///
 /// ```
 /// # use stackable_versioned_macros::versioned;
-/// #[versioned(version(name = "v1alpha1"), version(name = "v1beta1"))]
+/// #[versioned(
+///     version(name = "v1alpha1"),
+///     version(name = "v1beta1")
+/// )]
 /// pub struct Foo {
 ///     #[versioned(added(since = "v1beta1"))]
 ///     bar: usize,
@@ -161,123 +164,218 @@ mod consts;
 ///
 /// 1. The field `bar` is not yet present in version `v1alpha1` and is therefore
 ///    not generated.
-/// 2. Now the field `bar` is present in version `v1beta1`.
+/// 2. Now the field `bar` is present and uses `Default::default()` to populate
+///    the field during conversion. This function can be customized as shown
+///    later in this guide.
 ///
 /// ```ignore
 /// pub mod v1alpha1 {
 ///     use super::*;
-///     pub struct Foo {    // 1
+///     pub struct Foo {                 // 1
 ///         pub baz: bool,
 ///     }
 /// }
 ///
+/// impl From<v1alpha1::Foo> for v1beta1::Foo {
+///     fn from(foo: v1alpha1::Foo) -> Self {
+///         Self {
+///             bar: Default::default(), // 2
+///             baz: foo.baz,
+///         }
+///     }
+/// }
+///
 /// pub mod v1beta1 {
 ///     use super::*;
 ///     pub struct Foo {
-///         pub bar: usize, // 2
+///         pub bar: usize,              // 2
 ///         pub baz: bool,
 ///     }
 /// }
 /// ```
 /// </details>
 ///
-/// ### Changed Action
+/// #### Custom Default Function
 ///
-/// TODO.
+/// To customize the default function used in the generated `From` implementation
+/// you can use the `default` parameter. It expects a path to a function without
+/// braces.
 ///
-/// ### Deprecated Action
+/// ```
+/// # use stackable_versioned_macros::versioned;
+/// #[versioned(
+///     version(name = "v1alpha1"),
+///     version(name = "v1beta1")
+/// )]
+/// pub struct Foo {
+///     #[versioned(added(since = "v1beta1", default = "default_bar"))]
+///     bar: usize,
+///     baz: bool,
+/// }
+///
+/// fn default_bar() -> usize {
+///     42
+/// }
+/// ```
 ///
-/// TODO.
+/// <details>
+/// <summary>Generated code</summary>
 ///
-/// ### Auto-generated [`From`] Implementations
+/// 1. Instead of `Default::default()`, the provided function `default_bar()` is
+///    used. It is of course fully type checked and needs to return the expected
+///    type (`usize` in this case).
 ///
-/// To enable smooth version upgrades of the same container, the macro
-/// automatically generates [`From`] implementations. On a high level, code
-/// generated for two versions _a_ and _b_, with _a < b_ looks like this:
-/// `impl From<a> for b`.
+/// ```ignore
+/// // Snip
+///
+/// impl From<v1alpha1::Foo> for v1beta1::Foo {
+///     fn from(foo: v1alpha1::Foo) -> Self {
+///         Self {
+///             bar: default_bar(), // 1
+///             baz: foo.baz,
+///         }
+///     }
+/// }
+///
+/// // Snip
+/// ```
+/// </details>
+///
+/// ### Changed Action
+///
+/// This action indicates that an item is changed in a particular version. It
+/// combines renames and type changes into a single action. You can choose to
+/// change the name, change the type or do both. Available parameters are:
+///
+/// - `since` to indicate since which version the item is changed.
+/// - `from_name` to indicate from which previous name the field is renamed.
+/// - `from_type` to indicate from which previous type the field is changed.
 ///
 /// ```
 /// # use stackable_versioned_macros::versioned;
 /// #[versioned(
 ///     version(name = "v1alpha1"),
-///     version(name = "v1beta1"),
-///     version(name = "v1")
+///     version(name = "v1beta1")
 /// )]
 /// pub struct Foo {
-///     #[versioned(
-///         added(since = "v1beta1"),
-///         deprecated(since = "v1")
-///     )]
-///     deprecated_bar: usize,
+///     #[versioned(changed(
+///         since = "v1beta1",
+///         from_name = "prev_bar",
+///         from_type = "u16"
+///     ))]
+///     bar: usize,
 ///     baz: bool,
 /// }
 /// ```
 ///
 /// <details>
 /// <summary>Generated code</summary>
 ///
-/// 1. The field `bar` is not yet present in version `v1alpha1` and is therefore
-///    not generated.
-/// 2. Now the field `bar` is present and uses `Default::default()` to populate
-///    the field during conversion. This function can be customized as shown
-///    later in this guide.
-/// 3. In version `v1` the field `bar` is deprecated and as such includes the
-///    `deprecated_` prefix. Additionally, the `#[deprecated]` attribute is
-///    added to indicate that this part of the Rust code is deprecated. The
-///    note is optional.
+/// 1. In version `v1alpha1` the field is named `prev_bar` and uses a `u16`.
+/// 2. In the next version, `v1beta1`, the field is now named `bar` and uses
+///    `usize` instead of a `u16`. The `From` implementation transforms the
+///     type automatically via the `.into()` call.
 ///
 /// ```ignore
 /// pub mod v1alpha1 {
 ///     use super::*;
-///     pub struct Foo {                                 // 1
+///     pub struct Foo {
+///         pub prev_bar: u16,            // 1
 ///         pub baz: bool,
 ///     }
 /// }
 ///
 /// impl From<v1alpha1::Foo> for v1beta1::Foo {
-///     fn from(__sv_foo: v1alpha1::Foo) -> Self {
+///     fn from(foo: v1alpha1::Foo) -> Self {
 ///         Self {
-///             bar: ::std::default::Default::default(), // 2
-///             baz: __sv_foo.baz,
+///             bar: foo.prev_bar.into(), // 2
+///             baz: foo.baz,
 ///         }
 ///     }
 /// }
 ///
 /// pub mod v1beta1 {
 ///     use super::*;
 ///     pub struct Foo {
-///         pub bar: usize,
+///         pub bar: usize,               // 2
 ///         pub baz: bool,
 ///     }
 /// }
+/// ```
+/// </details>
 ///
-/// impl From<v1beta1::Foo> for v1::Foo {
-///     fn from(__sv_foo: v1beta1::Foo) -> Self {
+/// ### Deprecated Action
+///
+/// This action indicates that an item is deprecated in a particular version.
+/// Deprecated items are not removed.
+///
+/// ```
+/// # use stackable_versioned_macros::versioned;
+/// #[versioned(version(name = "v1alpha1"), version(name = "v1beta1"))]
+/// pub struct Foo {
+///     #[versioned(deprecated(since = "v1beta1"))]
+///     deprecated_bar: usize,
+///     baz: bool,
+/// }
+/// ```
+///
+/// <details>
+/// <summary>Generated code</summary>
+///
+/// 1. In version `v1alpha1` the field `bar` is not yet deprecated and thus uses
+///    the name without the `deprecated_` prefix.
+/// 2. In version `v1beta1` the field is deprecated and now includes the
+///    `deprecated_` prefix. It also uses the `#[deprecated]` attribute to
+///    indicate to Clippy this part of Rust code is deprecated. Therefore, the
+///    `From` implementation includes `#[allow(deprecated)]` to allow the
+///    usage of deprecated items in automatically generated code.
+///
+/// ```ignore
+/// pub mod v1alpha1 {
+///     use super::*;
+///     pub struct Foo {
+///         pub bar: usize,                     // 1
+///         pub baz: bool,
+///     }
+/// }
+///
+/// #[allow(deprecated)]                        // 2
+/// impl From<v1alpha1::Foo> for v1beta1::Foo {
+///     fn from(foo: v1alpha1::Foo) -> Self {
 ///         Self {
-///             deprecated_bar: __sv_foo.bar,            // 3
-///             baz: __sv_foo.baz,
+///             deprecated_bar: foo.bar,        // 2
+///             baz: foo.baz,
 ///         }
 ///     }
 /// }
 ///
-/// pub mod v1 {
+/// pub mod v1beta1 {
 ///     use super::*;
 ///     pub struct Foo {
-///         #[deprecated]                                // 3
+///         #[deprecated]                       // 2
 ///         pub deprecated_bar: usize,
 ///         pub baz: bool,
 ///     }
 /// }
 /// ```
 /// </details>
 ///
-/// ### Skip [`From`] Generation
+/// ## Auto-generated `From` Implementations
+///
+/// To enable smooth version upgrades of the same container, the macro
+/// automatically generates `From` implementations. On a high level, code
+/// generated for two versions _a_ and _b_, with _a < b_ looks like this:
+/// `impl From<a> for b`. As you can see, only upgrading is currently supported.
+/// Downgrading, so going from a higher version to a lower one, is not supported
+/// at the moment.
+///
+/// This automatic generation can be skipped to for example enable a custom
+/// implementation for more complex conversions.
 ///
-/// Generation of auto-generated [`From`] implementations can be skipped at the
-/// container and version level. This enables customization of the
-/// implementations if the default implementation is not sufficient.
+/// ### Skipping at the Container Level
 ///
-/// #### Skipping at the Container Level
+/// Disabling this feature on the container level results in no `From`
+/// implementation for all versions.
 ///
 /// ```
 /// # use stackable_versioned_macros::versioned;
@@ -290,39 +388,72 @@ mod consts;
 /// pub struct Foo {
 ///     #[versioned(
 ///         added(since = "v1beta1"),
-///         deprecated(since = "v1", note = "not needed")
+///         deprecated(since = "v1")
 ///     )]
 ///     deprecated_bar: usize,
 ///     baz: bool,
 /// }
 /// ```
 ///
-/// ### Customize Default Function for Added Fields
+/// ### Skipping at the Version Level
 ///
-/// It is possible to customize the default function used in the generated
-/// [`From`] implementation for populating added fields. By default,
-/// [`Default::default()`] is used.
+/// Disabling this feature at the version level results in no `From`
+/// implementation for that particular version. This can be read as "skip
+/// generation for converting _this_ version to the next one". In the example
+/// below no conversion between version `v1beta1` and `v1` is generated.
 ///
 /// ```
 /// # use stackable_versioned_macros::versioned;
 /// #[versioned(
 ///     version(name = "v1alpha1"),
-///     version(name = "v1beta1"),
+///     version(name = "v1beta1", skip(from)),
 ///     version(name = "v1")
 /// )]
 /// pub struct Foo {
 ///     #[versioned(
-///         added(since = "v1beta1", default = "default_bar"),
-///         deprecated(since = "v1", note = "not needed")
+///         added(since = "v1beta1"),
+///         deprecated(since = "v1")
 ///     )]
 ///     deprecated_bar: usize,
 ///     baz: bool,
 /// }
-///
-/// fn default_bar() -> usize {
-///     42
-/// }
 /// ```
+///
+/// ## Kubernetes-specific Features
+///
+/// This macro also offers support for Kubernetes-specific versioning,
+/// especially for CustomResourceDefinitions, short CRDs. These features are
+/// completely opt-in. You need to enable the `k8s` feature (which enables
+/// optional dependencies) and use the `k8s()` parameter in the macro.
+///
+#[cfg_attr(
+    feature = "k8s",
+    doc = r#"
+```
+# use stackable_versioned_macros::versioned;
+use schemars::JsonSchema;
+use serde::{Deserialize, Serialize};
+
+#[versioned(
+    version(name = "v1alpha1"),
+    version(name = "v1beta1"),
+    version(name = "v1"),
+    k8s(group = "example.com")
+)]
+#[derive(Clone, Debug, Deserialize, Serialize, JsonSchema)]
+pub struct FooSpec {
+    #[versioned(
+        added(since = "v1beta1"),
+        changed(since = "v1", from_name = "prev_bar", from_type = "u16")
+    )]
+    bar: usize,
+    baz: bool,
+}
+let merged_crd = Foo::merged_crd("v1").unwrap();
+println!("{}", serde_yaml::to_string(&merged_crd).unwrap());
+```
+"#
+)]
 #[proc_macro_attribute]
 pub fn versioned(attrs: TokenStream, input: TokenStream) -> TokenStream {
     let attrs = match NestedMeta::parse_meta_list(attrs.into()) {
@@ -334,7 +465,7 @@ pub fn versioned(attrs: TokenStream, input: TokenStream) -> TokenStream {
     };
 
     // NOTE (@Techassi): For now, we can just use the DeriveInput type here,
-    // because we only support structs (and eventually enums) to be versioned.
+    // because we only support structs end enums to be versioned.
     // In the future - if we decide to support modules - this requires
     // adjustments to also support modules. One possible solution might be to
     // use an enum with two variants: Container(DeriveInput) and