docs: Update field and variant attribute docs

Author: Techassi

crates/stackable-versioned-macros/src/attrs/common/item.rs

@@ -9,6 +9,12 @@ use crate::{
     consts::{DEPRECATED_FIELD_PREFIX, DEPRECATED_VARIANT_PREFIX},
 };
 
+/// This trait helps to unify attribute validation for both field and variant
+/// attributes.
+///
+/// This trait is implemented using a blanket implementation on types
+/// `T: Attributes`. The [`Attributes`] trait allows access to the common
+/// attributes shared across field and variant attributes.
 pub(crate) trait ValidateVersions<I>
 where
     I: Spanned,
@@ -79,6 +85,10 @@ where
     }
 }
 
+// NOTE (@Techassi): It might be possible (but is it required) to move this
+// functionality into a shared trait, which knows what type of item 'Self' is.
+
+/// This enum is used to run different validation based on the type of item.
 #[derive(Debug, strum::Display)]
 #[strum(serialize_all = "lowercase")]
 pub(crate) enum ItemType {
@@ -89,6 +99,15 @@ pub(crate) enum ItemType {
 /// These attributes are meant to be used in super structs, which add
 /// [`Field`](syn::Field) or [`Variant`](syn::Variant) specific attributes via
 /// darling's flatten feature. This struct only provides shared attributes.
+///
+/// ### Shared Item Rules
+///
+/// - An item can only ever be added once at most. An item not marked as 'added'
+///   is part of the container in every version until renamed or deprecated.
+/// - An item can be renamed many times. That's why renames are stored in a
+///   [`Vec`].
+/// - An item can only be deprecated once. A field not marked as 'deprecated'
+///   will be included up until the latest version.
 #[derive(Debug, FromMeta)]
 pub(crate) struct ItemAttributes {
     /// This parses the `added` attribute on items (fields or variants). It can

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

@@ -9,17 +9,13 @@ use crate::attrs::common::{ItemAttributes, ItemType};
 /// Data stored in this struct is validated using darling's `and_then` attribute.
 /// During darlings validation, it is not possible to validate that action
 /// versions match up with declared versions on the container. This validation
-/// can be done using the associated [`FieldAttributes::validate_versions`]
+/// can be done using the associated [`ValidateVersions::validate_versions`][1]
 /// function.
 ///
-/// ### Field Rules
+/// Rules shared across fields and variants can be found [here][2].
 ///
-/// - A field can only ever be added once at most. A field not marked as 'added'
-///   is part of the struct in every version until renamed or deprecated.
-/// - A field can be renamed many times. That's why renames are stored in a
-///   [`Vec`].
-/// - A field can only be deprecated once. A field not marked as 'deprecated'
-///   will be included up until the latest version.
+/// [1]: crate::attrs::common::ValidateVersions::validate_versions
+/// [2]: crate::attrs::common::ItemAttributes
 #[derive(Debug, FromField)]
 #[darling(
     attributes(versioned),
@@ -37,23 +33,18 @@ pub(crate) struct FieldAttributes {
 }
 
 impl FieldAttributes {
-    // NOTE (@Techassi): Ideally, these validations should be moved to the
-    // ItemAttributes impl, because common validation like action combinations
-    // and action order can be validated without taking the type of attribute
-    // into account (field vs variant). However, we would loose access to the
-    // field / variant ident and as such, cannot display the error directly on
-    // the affected field / variant. This is a significant decrease in DX.
-    // See https://github.com/TedDriggs/darling/discussions/294
-
     /// This associated function is called by darling (see and_then attribute)
     /// after it successfully parsed the attribute. This allows custom
     /// validation of the attribute which extends the validation already in
     /// place by darling.
     ///
     /// Internally, it calls out to other specialized validation functions.
     fn validate(self) -> Result<Self, Error> {
-        self.common
-            .validate(self.ident.as_ref().unwrap(), &ItemType::Field)?;
+        let ident = self
+            .ident
+            .as_ref()
+            .expect("internal error: field must have an ident");
+        self.common.validate(ident, &ItemType::Field)?;
 
         Ok(self)
     }

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

@@ -4,6 +4,19 @@ use syn::Ident;
 
 use crate::attrs::common::{ItemAttributes, ItemType};
 
+/// This struct describes all available variant attributes, as well as the
+/// variant name to display better diagnostics.
+///
+/// Data stored in this struct is validated using darling's `and_then` attribute.
+/// During darlings validation, it is not possible to validate that action
+/// versions match up with declared versions on the container. This validation
+/// can be done using the associated [`FieldAttributes::validate_versions`][1]
+/// function.
+///
+/// Rules shared across fields and variants can be found [here][2].
+///
+/// [1]: crate::attrs::common::ValidateVersions::validate_versions
+/// [2]: crate::attrs::common::ItemAttributes
 #[derive(Debug, FromVariant)]
 #[darling(
     attributes(versioned),
@@ -21,14 +34,6 @@ pub(crate) struct VariantAttributes {
 }
 
 impl VariantAttributes {
-    // NOTE (@Techassi): Ideally, these validations should be moved to the
-    // ItemAttributes impl, because common validation like action combinations
-    // and action order can be validated without taking the type of attribute
-    // into account (field vs variant). However, we would loose access to the
-    // field / variant ident and as such, cannot display the error directly on
-    // the affected field / variant. This is a significant decrease in DX.
-    // See https://github.com/TedDriggs/darling/discussions/294
-
     /// This associated function is called by darling (see and_then attribute)
     /// after it successfully parsed the attribute. This allows custom
     /// validation of the attribute which extends the validation already in