Feat: improve docs and standardize generics (#180)

Author: stegaBOB

example_programs/faction_enlistment/src/lib.rs

@@ -161,9 +161,11 @@ pub struct PlayerFactionData {
     pub enlisted_at_timestamp: i64,
     pub faction_id: FactionId,
     pub bump: u8,
+    /// Some docs!
     pub counter: CounterAccountData,
     pub _padding: [u64; 5],
     #[unsized_start]
+    /// Docs for Some fields!!
     some_fields: SomeFields,
 }
 

star_frame_proc/src/idl/instruction_to_idl.rs

@@ -1,8 +1,8 @@
 use crate::idl::{derive_type_to_idl_inner, TypeToIdlArgs};
-use crate::util::{ignore_cfg_module, reject_attributes, reject_generics, Paths};
+use crate::util::{ignore_cfg_module, new_generic, reject_attributes, reject_generics, Paths};
 use easy_proc::{find_attr, ArgumentList};
-use proc_macro2::{Ident, TokenStream};
-use quote::{format_ident, quote};
+use proc_macro2::TokenStream;
+use quote::quote;
 use syn::{parse_quote, DeriveInput};
 
 pub fn derive_instruction_to_idl(input: &DeriveInput) -> TokenStream {
@@ -28,7 +28,7 @@ pub fn derive_instruction_to_idl(input: &DeriveInput) -> TokenStream {
     let mut generics = input.generics.clone();
     let where_clause = generics.make_where_clause();
 
-    let generic_arg: Ident = format_ident!("__A");
+    let generic_arg = new_generic(&input.generics, None);
 
     where_clause.predicates.push(
         parse_quote!(<Self as #prelude::StarFrameInstruction>::Accounts<'b, 'c>: #prelude::AccountSetToIdl<#generic_arg>),

star_frame_proc/src/unsize/struct_impl.rs

@@ -11,7 +11,7 @@ use proc_macro2::Ident;
 use proc_macro2::TokenStream;
 use proc_macro_error2::abort;
 use quote::{format_ident, quote};
-use syn::{parse_quote, Field, Generics, ItemStruct, Lifetime, Type, Visibility};
+use syn::{parse_quote, Attribute, Field, Generics, ItemStruct, Lifetime, Type, Visibility};
 
 #[allow(non_snake_case)]
 macro_rules! UnsizedStructContext {
@@ -120,6 +120,7 @@ pub struct UnsizedStructContext {
     sized_field_types: Vec<Type>,
     unsized_field_idents: Vec<Ident>,
     unsized_field_types: Vec<Type>,
+    with_sized_docs: Vec<Vec<Attribute>>,
     with_sized_idents: Vec<Ident>,
     with_sized_types: Vec<Type>,
     with_sized_vis: Vec<Visibility>,
@@ -212,14 +213,29 @@ impl UnsizedStructContext {
 
         let sized_field_ident = sized_ident
             .as_ref()
-            .map(|_| new_ident("__sized", get_field_idents(&all_fields), true));
+            .map(|_| new_ident("_sized", get_field_idents(&all_fields), true));
 
         let sized_field_idents = get_field_idents(&sized_fields).cloned().collect_vec();
         let sized_field_types = get_field_types(&sized_fields).cloned().collect_vec();
         let unsized_field_idents = get_field_idents(&unsized_fields).cloned().collect_vec();
         let unsized_field_types = get_field_types(&unsized_fields).cloned().collect_vec();
         let unsized_field_vis = get_field_vis(&unsized_fields).cloned().collect_vec();
 
+        let with_sized_docs = sized_field_ident
+            .as_ref()
+            .map(|_ident| {
+                vec![parse_quote! {
+                    #[doc = "Sized portion of the Unsized Type"]
+                }]
+            })
+            .into_iter()
+            .chain(
+                unsized_fields
+                    .iter()
+                    .map(|field| get_doc_attributes(&field.attrs)),
+            )
+            .collect_vec();
+
         let with_sized_idents = sized_field_ident
             .iter()
             .chain(unsized_field_idents.iter())
@@ -267,6 +283,7 @@ impl UnsizedStructContext {
             sized_field_types,
             unsized_field_idents,
             unsized_field_types,
+            with_sized_docs,
             with_sized_idents,
             with_sized_types,
             with_sized_vis,
@@ -308,15 +325,19 @@ impl UnsizedStructContext {
 
     fn ref_struct(&self) -> TokenStream {
         Paths!(prelude);
-        UnsizedStructContext!(self => vis, ref_ident, with_sized_vis, with_sized_idents, with_sized_types, top_lt);
+        UnsizedStructContext!(self => vis, ref_ident, with_sized_vis, with_sized_idents, with_sized_types, top_lt, with_sized_docs);
         let (generics, wc) = self.split_for_declaration(true);
         let transparent = (with_sized_idents.len() == 1).then(|| quote!(#[repr(transparent)]));
+
+        let doc = format!("Ref type for [`{}`]", self.struct_ident);
         quote! {
+            #[doc = #doc]
             #[derive(#prelude::DeriveWhere)]
             #[derive_where(Debug; #(<#with_sized_types as #prelude::UnsizedType>::Ref<#top_lt>,)*)]
             #transparent
             #vis struct #ref_ident #generics #wc {
                 #(
+                    #(#with_sized_docs)*
                     #with_sized_vis #with_sized_idents: <#with_sized_types as #prelude::UnsizedType>::Ref<#top_lt>,
                 )*
             }
@@ -325,16 +346,19 @@ impl UnsizedStructContext {
 
     fn mut_struct(&self) -> TokenStream {
         Paths!(prelude);
-        UnsizedStructContext!(self => vis, mut_ident, top_lt, with_sized_vis, with_sized_idents, with_sized_types);
+        UnsizedStructContext!(self => vis, mut_ident, top_lt, with_sized_vis, with_sized_idents, with_sized_types, with_sized_docs);
         let (generics, wc) = self.split_for_declaration(true);
         let transparent = (with_sized_idents.len() == 1).then(|| quote!(#[repr(transparent)]));
 
+        let doc = format!("Mut type for [`{}`]", self.struct_ident);
         quote! {
+            #[doc = #doc]
             #[derive(#prelude::DeriveWhere)]
             #[derive_where(Debug; #(<#with_sized_types as #prelude::UnsizedType>::Mut<#top_lt>,)*)]
             #transparent
             #vis struct #mut_ident #generics #wc {
                 #(
+                    #(#with_sized_docs)*
                     #with_sized_vis #with_sized_idents: <#with_sized_types as #prelude::UnsizedType>::Mut<#top_lt>,
                 )*
             }
@@ -351,8 +375,10 @@ impl UnsizedStructContext {
         let owned_types = get_field_types(owned_fields).collect_vec();
         let lt = new_lifetime(&self.generics, None);
 
+        let doc = format!("Owned type for [`{}`]", self.struct_ident);
         quote! {
             #(#[#additional_attributes])*
+            #[doc = #doc]
             #[derive(#prelude::DeriveWhere)]
             #[derive_where(Debug, Copy, Clone, Default, Eq, Hash, Ord, PartialEq, PartialOrd; #(for<#lt> #owned_types,)*)]
             #vis struct #owned_ident #gen #where_clause {
@@ -388,8 +414,10 @@ impl UnsizedStructContext {
                 #program_account
             )
         });
+        let doc = format!("Sized portion of [`{}`]", self.struct_ident);
         let sized_struct = quote! {
             #(#[#additional_attributes])*
+            #[doc = #doc]
             #[derive(#prelude::Align1, #sized_bytemuck_derives)]
             #sized_attributes
             #[repr(C, packed)]

star_frame_proc/src/util/generics.rs

@@ -195,7 +195,7 @@ pub fn reject_generics(item: &impl GetGenerics, error: Option<&str>) {
 }
 
 pub fn phantom_generics_ident() -> Ident {
-    format_ident!("__generics")
+    format_ident!("_generics")
 }
 
 pub fn phantom_generics_type(item: &impl GetGenerics) -> Option<Type> {