Refactor: Rename Container to StructInfo

The terminology "Container" is "inside baseball" for things in Rust that can contain something else: A tuple struct, a named structure, an enum, etc. In our case we only deal with named structs so this can be specialized to something people who aren't intimately familiar with proc macro terminology can visualize a bit better.

Author: schneems

cache_diff_derive/src/fields.rs

@@ -28,7 +28,7 @@ impl CacheDiffField {
     fn new(
         field: &Field,
         attributes: CacheDiffAttributes,
-        container: &Container,
+        container: &StructInfo,
     ) -> syn::Result<Option<Self>> {
         if let Some(ignore) = attributes.ignore {
             if ignore == "custom" && container.custom.is_none() {
@@ -81,29 +81,42 @@ fn is_pathbuf(ty: &syn::Type) -> bool {
     false
 }
 
-/// Represents a single attribute on a container AKA a struct
+/// Represents a single (comma delimited) `cache_diff` attribute on the Struct
+///
+/// These are also called "container attributes" in proc-macro terminology however
+/// the only container we support are structs.
+///
+/// A [StructInfo] can be built out of one or more attributes
 #[derive(Debug, Default)]
-struct ContainerAttribute {
+struct StructAttribute {
+    /// #[cache_diff(custom = <diff function path>)]
     custom: Option<syn::Path>,
 }
 
-/// Represents the Struct
-struct Container {
+/// Represents the configuration on the Struct
+///
+/// Proc macros can be configured by using attributes like `#[cache_diff(...)]`. These can apply to
+/// fields or the container that holds those fields. This proc macro only supports
+/// named Struct containers so this finalized attribute information is stored in [StructInfo].
+struct StructInfo {
+    /// Name of the struct i.e. `struct Foo {}` would be `Foo`
     identifier: Ident,
+    /// Path to a custom diff function, comes from [StructAttribute] parsing
     custom: Option<syn::Path>,
+    /// The fields of a struct i.e. `struct Example { name: String }` would hold `[name: String]` (more or less)
     fields: Punctuated<Field, Comma>,
 }
 
-impl Container {
+impl StructInfo {
     fn from_ast(input: &syn::DeriveInput) -> syn::Result<Self> {
         let identifier = input.ident.clone();
         let attrs = input.attrs.clone();
 
         let attributes = attrs
             .iter()
             .filter(|attr| attr.path().is_ident("cache_diff"))
-            .map(|attr| attr.parse_args_with(ContainerAttribute::parse))
-            .collect::<syn::Result<Vec<ContainerAttribute>>>()?;
+            .map(|attr| attr.parse_args_with(StructAttribute::parse))
+            .collect::<syn::Result<Vec<StructAttribute>>>()?;
 
         if attributes.len() > 1 {
             return Err(syn::Error::new(
@@ -122,22 +135,22 @@ impl Container {
         }
         .to_owned();
 
-        Ok(Container {
+        Ok(StructInfo {
             identifier,
             custom,
             fields,
         })
     }
 }
 
-impl Parse for ContainerAttribute {
+impl Parse for StructAttribute {
     fn parse(input: syn::parse::ParseStream) -> syn::Result<Self> {
         let name: Ident = input.parse()?;
         let name_str = name.to_string();
         match name_str.as_ref() {
             "custom" => {
                 input.parse::<syn::Token![=]>()?;
-                Ok(ContainerAttribute { custom: Some(input.parse()?) })
+                Ok(StructAttribute { custom: Some(input.parse()?) })
             }
             _ => Err(syn::Error::new(
                 name.span(),
@@ -151,10 +164,10 @@ impl Parse for ContainerAttribute {
 
 pub fn create_cache_diff(item: TokenStream) -> syn::Result<TokenStream> {
     let ast: DeriveInput = syn::parse2(item).unwrap();
-    let container = Container::from_ast(&ast)?;
-    let struct_identifier = &container.identifier;
+    let struct_info = StructInfo::from_ast(&ast)?;
+    let struct_identifier = &struct_info.identifier;
 
-    let custom_diff = if let Some(ref custom_fn) = container.custom {
+    let custom_diff = if let Some(ref custom_fn) = struct_info.custom {
         quote! {
             let custom_diff = #custom_fn(old, self);
             for diff in &custom_diff {
@@ -166,9 +179,9 @@ pub fn create_cache_diff(item: TokenStream) -> syn::Result<TokenStream> {
     };
 
     let mut comparisons = Vec::new();
-    for f in container.fields.iter() {
+    for f in struct_info.fields.iter() {
         let attributes = CacheDiffAttributes::from(f)?;
-        let field = CacheDiffField::new(f, attributes, &container)?;
+        let field = CacheDiffField::new(f, attributes, &struct_info)?;
 
         if let Some(CacheDiffField {
             field_identifier: field_ident,