Merge branch 'master' into staking

proc-macro/src/lib.rs

@@ -30,13 +30,111 @@ use synstructure::{
     Structure,
 };
 
+/// Register type sizes for [EventsDecoder](struct.EventsDecoder.html) and set the `MODULE`.
+///
+/// The `module` macro registers the type sizes of the associated types of a trait so that [EventsDecoder](struct.EventsDecoder.html)
+/// can decode events of that type when received from Substrate. It also sets the `MODULE` constant
+/// to the name of the trait (must match the name of the Substrate pallet) that enables the [Call](), [Event]() and [Store]() macros to work.
+///
+/// If you do not want an associated type to be registered, likely because you never expect it as part of a response payload to be decoded, use `#[module(ignore)]` on the type.
+///
+/// Example:
+///
+/// ```ignore
+/// #[module]
+/// pub trait Herd: Husbandry {
+///     type Hooves: HoofCounter;
+///     type Wool: WoollyAnimal;
+///     #[module(ignore)]
+///     type Digestion: EnergyProducer + std::fmt::Debug;
+/// }
+/// ```
+///
+/// The above will produce the following code:
+///
+/// ```ignore
+/// pub trait Herd: Husbandry {
+///     type Hooves: HoofCounter;
+///     type Wool: WoollyAnimal;
+///     #[module(ignore)]
+///     type Digestion: EnergyProducer + std::fmt::Debug;
+/// }
+///
+/// const MODULE: &str = "Herd";
+///
+/// // `EventsDecoder` extension trait.
+/// pub trait HerdEventsDecoder {
+///     // Registers this modules types.
+///     fn with_herd(&mut self);
+/// }
+///
+/// impl<T: Herd> HerdEventsDecoder for
+///     substrate_subxt::EventsDecoder<T>
+/// {
+///     fn with_herd(&mut self) {
+///         self.with_husbandry();
+///         self.register_type_size::<T::Hooves>("Hooves");
+///         self.register_type_size::<T::Wool>("Wool");
+///     }
+/// }
+/// ```
+///
+/// The following type sizes are registered by default: `bool, u8, u32, AccountId, AccountIndex,
+/// AuthorityId, AuthorityIndex, AuthorityWeight, BlockNumber, DispatchInfo, Hash, Kind,
+/// MemberCount, PhantomData, PropIndex, ProposalIndex, ReferendumIndex, SessionIndex, VoteThreshold`
 #[proc_macro_attribute]
 #[proc_macro_error]
 pub fn module(args: TokenStream, input: TokenStream) -> TokenStream {
     module::module(args.into(), input.into()).into()
 }
 
-decl_derive!([Call] => #[proc_macro_error] call);
+decl_derive!(
+    [Call] =>
+    /// Derive macro that implements [substrate_subxt::Call](../substrate_subxt/trait.Call.html) for your struct
+    /// and defines&implements the calls as an extension trait.
+    ///
+    /// Use the `Call` derive macro in tandem with the [#module](../substrate_subxt/attr.module.html) macro to extend
+    /// your struct to enable calls to substrate and to decode events. The struct maps to the corresponding Substrate runtime call, e.g.:
+    ///
+    /// ```ignore
+    /// decl_module! {
+    ///     /* … */
+    ///     pub fn fun_stuff(origin, something: Vec<u8>) -> DispatchResult { /* … */ }
+    ///     /* … */
+    /// }
+    ///```
+    ///
+    /// Implements [substrate_subxt::Call](../substrate_subxt/trait.Call.html) and adds an extension trait that
+    /// provides two methods named as your struct.
+    ///
+    /// Example:
+    /// ```rust,ignore
+    /// pub struct MyRuntime;
+    ///
+    /// impl System for MyRuntime { /* … */ }
+    /// impl Balances for MyRuntime { /* … */ }
+    ///
+    /// #[module]
+    /// pub trait MyTrait: System + Balances {}
+    ///
+    /// #[derive(Call)]
+    /// pub struct FunStuffCall<T: MyTrait> {
+    ///     /// Runtime marker.
+    ///     pub _runtime: PhantomData<T>,
+    ///     /// The argument passed to the call..
+    ///     pub something: Vec<u8>,
+    /// }
+    /// ```
+    ///
+    /// When building a [Client](../substrate_subxt/struct.Client.html) parameterised to `MyRuntime`, you have access to
+    /// two new methods: `fun_stuff()` and `fun_stuff_and_watch()` by way of the derived `FunStuffExt`
+    /// trait. The `_and_watch` variant makes the call and waits for the result. The fields of the
+    /// input struct become arguments to the calls (ignoring the marker field).
+    ///
+    /// Under the hood the implementation calls [submit()](../substrate_subxt/struct.Client.html#method.submit) and
+    /// [watch()](../substrate_subxt/struct.Client.html#method.watch) respectively.
+    #[proc_macro_error] call
+);
 fn call(s: Structure) -> TokenStream {
     call::call(s).into()
 }

proc-macro/src/module.rs

@@ -69,7 +69,7 @@ fn events_decoder_trait_name(module: &syn::Ident) -> syn::Ident {
 fn with_module_ident(module: &syn::Ident) -> syn::Ident {
     format_ident!("with_{}", module.to_string().to_snake_case())
 }
-
+/// Attribute macro that registers the type sizes used by the module; also sets the `MODULE` constant.
 pub fn module(_args: TokenStream, tokens: TokenStream) -> TokenStream {
     let input: Result<syn::ItemTrait, _> = syn::parse2(tokens.clone());
     let input = if let Ok(input) = input {
@@ -187,4 +187,46 @@ mod tests {
         let result = module(attr, input);
         utils::assert_proc_macro(result, expected);
     }
+
+    #[test]
+    fn test_herd() {
+        let attr = quote!(#[module]);
+        let input = quote! {
+            pub trait Herd: Husbandry {
+                type Hoves: u8;
+                type Wool: bool;
+                #[module(ignore)]
+                type Digestion: EnergyProducer + fmt::Debug;
+            }
+        };
+        let expected = quote! {
+            pub trait Herd: Husbandry {
+                type Hoves: u8;
+                type Wool: bool;
+                #[module(ignore)]
+                type Digestion: EnergyProducer + fmt::Debug;
+            }
+
+            const MODULE: &str = "Herd";
+
+            /// `EventsDecoder` extension trait.
+            pub trait HerdEventsDecoder {
+                /// Registers this modules types.
+                fn with_herd(&mut self);
+            }
+
+            impl<T: Herd> HerdEventsDecoder for
+                substrate_subxt::EventsDecoder<T>
+            {
+                fn with_herd(&mut self) {
+                    self.with_husbandry();
+                    self.register_type_size::<T::Hoves>("Hoves");
+                    self.register_type_size::<T::Wool>("Wool");
+                }
+            }
+        };
+
+        let result = module(attr, input);
+        utils::assert_proc_macro(result, expected);
+    }
 }