From 1cba624d98b8ff5dda830afd0c653ecaa62baa86 Mon Sep 17 00:00:00 2001 From: David Palm Date: Mon, 6 Jul 2020 16:52:08 +0200 Subject: [PATCH 1/4] Document the `Call` derive macro --- examples/submit_and_watch.rs | 3 ++- proc-macro/src/lib.rs | 38 +++++++++++++++++++++++++++++++++++- 2 files changed, 39 insertions(+), 2 deletions(-) diff --git a/examples/submit_and_watch.rs b/examples/submit_and_watch.rs index 81701f7383..e5dfc4818b 100644 --- a/examples/submit_and_watch.rs +++ b/examples/submit_and_watch.rs @@ -16,7 +16,8 @@ use sp_keyring::AccountKeyring; use substrate_subxt::{ - balances::*, + // Traits derived by the `Call` macro + balances::{TransferCallExt, TransferEventExt}, ClientBuilder, DefaultNodeRuntime, PairSigner, diff --git a/proc-macro/src/lib.rs b/proc-macro/src/lib.rs index ccbea7e2b4..8f84f54163 100644 --- a/proc-macro/src/lib.rs +++ b/proc-macro/src/lib.rs @@ -36,7 +36,43 @@ 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. + /// 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 { + /// /// Runtime marker. + /// pub _runtime: PhantomData, + /// /// The argument passed to the call.. + /// pub something: Vec, + /// } + /// ``` + /// + /// When building a [Client](../substrate_subxt/struct.Client.html) parametrised to `MyRuntime`, you have access to + /// two new methods: `fun_stuff()` and `fun_stuff_and_watch()` by way of the derived `FunStuffExt` trait. 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() } From bbadd437df1a7635c3465d591a32cd8c7df48e70 Mon Sep 17 00:00:00 2001 From: David Palm Date: Mon, 6 Jul 2020 16:54:41 +0200 Subject: [PATCH 2/4] Obey the fmt --- examples/submit_and_watch.rs | 6 ++++-- 1 file changed, 4 insertions(+), 2 deletions(-) diff --git a/examples/submit_and_watch.rs b/examples/submit_and_watch.rs index e5dfc4818b..c75137f994 100644 --- a/examples/submit_and_watch.rs +++ b/examples/submit_and_watch.rs @@ -16,8 +16,10 @@ use sp_keyring::AccountKeyring; use substrate_subxt::{ - // Traits derived by the `Call` macro - balances::{TransferCallExt, TransferEventExt}, + balances::{ + TransferCallExt, + TransferEventExt, + }, ClientBuilder, DefaultNodeRuntime, PairSigner, From 528aa819250cb51de83784fbaae2ddc8d3f21da6 Mon Sep 17 00:00:00 2001 From: David Date: Tue, 7 Jul 2020 08:57:28 +0200 Subject: [PATCH 3/4] Update proc-macro/src/lib.rs Co-authored-by: Andrew Jones --- proc-macro/src/lib.rs | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/proc-macro/src/lib.rs b/proc-macro/src/lib.rs index 8f84f54163..4fd3b23c64 100644 --- a/proc-macro/src/lib.rs +++ b/proc-macro/src/lib.rs @@ -65,7 +65,7 @@ decl_derive!( /// } /// ``` /// - /// When building a [Client](../substrate_subxt/struct.Client.html) parametrised to `MyRuntime`, you have access to + /// 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 fields /// of the input struct become arguments to the calls (ignoring the marker field). /// From 062b36684c0e918ebe14a734d2c71cf35ba3b2b4 Mon Sep 17 00:00:00 2001 From: David Palm Date: Tue, 7 Jul 2020 09:05:44 +0200 Subject: [PATCH 4/4] Review feedback --- proc-macro/src/lib.rs | 18 ++++++++++++++---- 1 file changed, 14 insertions(+), 4 deletions(-) diff --git a/proc-macro/src/lib.rs b/proc-macro/src/lib.rs index 4fd3b23c64..90dca686e4 100644 --- a/proc-macro/src/lib.rs +++ b/proc-macro/src/lib.rs @@ -42,9 +42,18 @@ decl_derive!( /// 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. + /// 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) -> DispatchResult { /* … */ } + /// /* … */ + /// } + ///``` + /// /// Implements [substrate_subxt::Call](../substrate_subxt/trait.Call.html) and adds an extension trait that - /// provides two methods named as your struct. + /// provides two methods named as your struct. /// /// Example: /// ```rust,ignore @@ -66,8 +75,9 @@ decl_derive!( /// ``` /// /// 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 fields - /// of the input struct become arguments to the calls (ignoring the marker field). + /// 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.