From b53b64d02417b88b2196b96d736622ccf48b630b Mon Sep 17 00:00:00 2001 From: thiolliere Date: Thu, 21 Mar 2019 11:56:24 +0100 Subject: [PATCH 1/6] improve decl_storage instance doc --- srml/support/procedural/src/storage/transformation.rs | 8 +++++--- 1 file changed, 5 insertions(+), 3 deletions(-) diff --git a/srml/support/procedural/src/storage/transformation.rs b/srml/support/procedural/src/storage/transformation.rs index af9c79427085a..e394b8070cf0f 100644 --- a/srml/support/procedural/src/storage/transformation.rs +++ b/srml/support/procedural/src/storage/transformation.rs @@ -500,6 +500,7 @@ fn decl_storage_items( } impls.extend(quote! { + /// Instance trait implemented by all usable instance of the module. pub trait #instantiable: 'static { #const_impls } @@ -510,12 +511,12 @@ fn decl_storage_items( .map(|i| { let name = format!("Instance{}", i); let ident = syn::Ident::new(&name, proc_macro2::Span::call_site()); - (name, ident) + (name, ident, quote! {#[doc=r"Module instance"]}) }) - .chain(default_instance.clone().map(|ident| (String::new(), ident))); + .chain(default_instance.clone().map(|ident| (String::new(), ident, quote! {#[doc=r"Default module instance"]}))); // Impl Instance trait for instances - for (prefix, ident) in instances { + for (prefix, ident, doc) in instances { let mut const_impls = TokenStream2::new(); for (const_name, partial_const_value) in &const_names { @@ -529,6 +530,7 @@ fn decl_storage_items( // Those trait are derived because of wrong bounds for generics #[cfg_attr(feature = "std", derive(Debug))] #[derive(Clone, Eq, PartialEq, #scrate::codec::Encode, #scrate::codec::Decode)] + #doc pub struct #ident; impl #instantiable for #ident { #const_impls From 56e966f7c794b0a34e79814aa8f255be969b260b Mon Sep 17 00:00:00 2001 From: thiolliere Date: Thu, 21 Mar 2019 11:56:40 +0100 Subject: [PATCH 2/6] use decl_event doc accordignly --- srml/assets/src/lib.rs | 4 +--- srml/council/src/motions.rs | 2 +- srml/council/src/voting.rs | 2 +- srml/example/src/lib.rs | 6 +++--- srml/grandpa/src/lib.rs | 2 +- srml/session/src/lib.rs | 2 +- srml/staking/src/lib.rs | 2 +- srml/sudo/src/lib.rs | 2 +- srml/system/src/lib.rs | 2 +- srml/treasury/src/lib.rs | 10 +--------- 10 files changed, 12 insertions(+), 22 deletions(-) diff --git a/srml/assets/src/lib.rs b/srml/assets/src/lib.rs index 14dba1d198dd5..92cc75b33791e 100644 --- a/srml/assets/src/lib.rs +++ b/srml/assets/src/lib.rs @@ -82,10 +82,8 @@ decl_module! { } } -/// An event in this module. Events are simple means of reporting specific conditions and -/// circumstances that have happened that users, Dapps and/or chain explorers would find -/// interesting and otherwise difficult to detect. decl_event!( + /// An event in this module. pub enum Event where ::AccountId, ::Balance { /// Some assets were issued. Issued(AssetId, AccountId, Balance), diff --git a/srml/council/src/motions.rs b/srml/council/src/motions.rs index 7d9783fd33bb5..1f119434cf897 100644 --- a/srml/council/src/motions.rs +++ b/srml/council/src/motions.rs @@ -47,8 +47,8 @@ pub enum Origin { Members(u32), } -/// Event for this module. decl_event!( + /// Event for this module. pub enum Event where ::Hash, ::AccountId { /// A motion (given hash) has been proposed (by given account) with a threshold (given u32). Proposed(AccountId, ProposalIndex, Hash, u32), diff --git a/srml/council/src/voting.rs b/srml/council/src/voting.rs index c365ea8021d7d..fc108e4974040 100644 --- a/srml/council/src/voting.rs +++ b/srml/council/src/voting.rs @@ -125,8 +125,8 @@ decl_storage! { } } -/// An event in this module. decl_event!( + /// An event in this module. pub enum Event where ::Hash { /// A voting tally has happened for a referendum cancellation vote. /// Last three are yes, no, abstain counts. diff --git a/srml/example/src/lib.rs b/srml/example/src/lib.rs index 452e75ccc340f..c8537fca6489b 100644 --- a/srml/example/src/lib.rs +++ b/srml/example/src/lib.rs @@ -72,10 +72,10 @@ decl_storage! { } } -/// An event in this module. Events are simple means of reporting specific conditions and -/// circumstances that have happened that users, Dapps and/or chain explorers would find -/// interesting and otherwise difficult to detect. decl_event!( + /// An event in this module. Events are simple means of reporting specific conditions and + /// circumstances that have happened that users, Dapps and/or chain explorers would find + /// interesting and otherwise difficult to detect. pub enum Event where B = ::Balance { // Just a normal `enum`, here's a dummy event to ensure it compiles. /// Dummy event, just here so there's a generic type that's used. diff --git a/srml/grandpa/src/lib.rs b/srml/grandpa/src/lib.rs index 0715ce034ad7b..6b9a1a7013fa2 100644 --- a/srml/grandpa/src/lib.rs +++ b/srml/grandpa/src/lib.rs @@ -176,8 +176,8 @@ impl Decode for StoredPendingChange where ::SessionKey { /// New authority set has been applied. NewAuthorities(Vec<(SessionKey, u64)>), diff --git a/srml/session/src/lib.rs b/srml/session/src/lib.rs index 47fb0fca41734..4628c76a21396 100644 --- a/srml/session/src/lib.rs +++ b/srml/session/src/lib.rs @@ -84,8 +84,8 @@ decl_module! { } } -/// An event in this module. decl_event!( + /// An event in this module. pub enum Event where ::BlockNumber { /// New session has happened. Note that the argument is the session index, not the block /// number as the type might suggest. diff --git a/srml/staking/src/lib.rs b/srml/staking/src/lib.rs index 151668f691be5..fc101164ff618 100644 --- a/srml/staking/src/lib.rs +++ b/srml/staking/src/lib.rs @@ -488,8 +488,8 @@ decl_module! { } } -/// An event in this module. decl_event!( + /// An event in this module. pub enum Event where Balance = BalanceOf, ::AccountId { /// All validators have been rewarded by the given balance. Reward(Balance), diff --git a/srml/sudo/src/lib.rs b/srml/sudo/src/lib.rs index e4dfa480e9e3e..f3319868dd384 100644 --- a/srml/sudo/src/lib.rs +++ b/srml/sudo/src/lib.rs @@ -58,8 +58,8 @@ decl_module! { } } -/// An event in this module. decl_event!( + /// An event in this module. pub enum Event where AccountId = ::AccountId { /// A sudo just took place. Sudid(bool), diff --git a/srml/system/src/lib.rs b/srml/system/src/lib.rs index c5397345a1e95..b8d2ff0268a22 100644 --- a/srml/system/src/lib.rs +++ b/srml/system/src/lib.rs @@ -124,8 +124,8 @@ pub struct EventRecord { pub event: E, } -/// Event for the system module. decl_event!( + /// Event for the system module. pub enum Event { /// An extrinsic completed successfully. ExtrinsicSuccess, diff --git a/srml/treasury/src/lib.rs b/srml/treasury/src/lib.rs index 8585950f7c1ec..2d9a0343c3415 100644 --- a/srml/treasury/src/lib.rs +++ b/srml/treasury/src/lib.rs @@ -31,11 +31,6 @@ type BalanceOf = <::Currency as Currency<::Ac type PositiveImbalanceOf = <::Currency as Currency<::AccountId>>::PositiveImbalance; type NegativeImbalanceOf = <::Currency as Currency<::AccountId>>::NegativeImbalance; -/// Our module's configuration trait. All our types and consts go in here. If the -/// module is dependent on specific other modules, then their configuration traits -/// should be added to our implied traits list. -/// -/// `system::Trait` should always be included in our implied traits. pub trait Trait: system::Trait { /// The staking balance. type Currency: Currency; @@ -58,10 +53,7 @@ pub trait Trait: system::Trait { type ProposalIndex = u32; -// The module declaration. This states the entry points that we handle. The -// macro takes care of the marshalling of arguments and dispatch. decl_module! { - // Simple declaration of the `Module` type. Lets the macro know what its working on. pub struct Module for enum Call where origin: T::Origin { fn deposit_event() = default; /// Put forward a suggestion for spending. A deposit proportional to the value @@ -177,8 +169,8 @@ decl_storage! { } } -/// An event in this module. decl_event!( + /// An event in this module. pub enum Event where Balance = BalanceOf, From e3ba1bf33f2b64ed7e4ace1bb6463b2a1ff14f5e Mon Sep 17 00:00:00 2001 From: thiolliere Date: Fri, 22 Mar 2019 16:45:25 +0100 Subject: [PATCH 3/6] automate doc and while allow to extend it on event --- srml/assets/src/lib.rs | 1 - srml/council/src/motions.rs | 1 - srml/council/src/voting.rs | 1 - srml/example/src/lib.rs | 2 +- srml/grandpa/src/lib.rs | 1 - srml/session/src/lib.rs | 1 - srml/staking/src/lib.rs | 1 - srml/sudo/src/lib.rs | 1 - srml/support/src/event.rs | 5 +++++ srml/system/src/lib.rs | 1 - srml/treasury/src/lib.rs | 1 - 11 files changed, 6 insertions(+), 10 deletions(-) diff --git a/srml/assets/src/lib.rs b/srml/assets/src/lib.rs index 92cc75b33791e..7a23a0d70a1a3 100644 --- a/srml/assets/src/lib.rs +++ b/srml/assets/src/lib.rs @@ -83,7 +83,6 @@ decl_module! { } decl_event!( - /// An event in this module. pub enum Event where ::AccountId, ::Balance { /// Some assets were issued. Issued(AssetId, AccountId, Balance), diff --git a/srml/council/src/motions.rs b/srml/council/src/motions.rs index 1f119434cf897..3bbe463780c46 100644 --- a/srml/council/src/motions.rs +++ b/srml/council/src/motions.rs @@ -48,7 +48,6 @@ pub enum Origin { } decl_event!( - /// Event for this module. pub enum Event where ::Hash, ::AccountId { /// A motion (given hash) has been proposed (by given account) with a threshold (given u32). Proposed(AccountId, ProposalIndex, Hash, u32), diff --git a/srml/council/src/voting.rs b/srml/council/src/voting.rs index fc108e4974040..4c5c62dc838b5 100644 --- a/srml/council/src/voting.rs +++ b/srml/council/src/voting.rs @@ -126,7 +126,6 @@ decl_storage! { } decl_event!( - /// An event in this module. pub enum Event where ::Hash { /// A voting tally has happened for a referendum cancellation vote. /// Last three are yes, no, abstain counts. diff --git a/srml/example/src/lib.rs b/srml/example/src/lib.rs index c8537fca6489b..1e24996f497aa 100644 --- a/srml/example/src/lib.rs +++ b/srml/example/src/lib.rs @@ -73,7 +73,7 @@ decl_storage! { } decl_event!( - /// An event in this module. Events are simple means of reporting specific conditions and + /// Events are simple means of reporting specific conditions and /// circumstances that have happened that users, Dapps and/or chain explorers would find /// interesting and otherwise difficult to detect. pub enum Event where B = ::Balance { diff --git a/srml/grandpa/src/lib.rs b/srml/grandpa/src/lib.rs index 6b9a1a7013fa2..3c85756e96ba6 100644 --- a/srml/grandpa/src/lib.rs +++ b/srml/grandpa/src/lib.rs @@ -177,7 +177,6 @@ impl Decode for StoredPendingChange where ::SessionKey { /// New authority set has been applied. NewAuthorities(Vec<(SessionKey, u64)>), diff --git a/srml/session/src/lib.rs b/srml/session/src/lib.rs index 4628c76a21396..c49f021b611a4 100644 --- a/srml/session/src/lib.rs +++ b/srml/session/src/lib.rs @@ -85,7 +85,6 @@ decl_module! { } decl_event!( - /// An event in this module. pub enum Event where ::BlockNumber { /// New session has happened. Note that the argument is the session index, not the block /// number as the type might suggest. diff --git a/srml/staking/src/lib.rs b/srml/staking/src/lib.rs index fc101164ff618..b9f27e9703649 100644 --- a/srml/staking/src/lib.rs +++ b/srml/staking/src/lib.rs @@ -489,7 +489,6 @@ decl_module! { } decl_event!( - /// An event in this module. pub enum Event where Balance = BalanceOf, ::AccountId { /// All validators have been rewarded by the given balance. Reward(Balance), diff --git a/srml/sudo/src/lib.rs b/srml/sudo/src/lib.rs index f3319868dd384..b0650cf373ef7 100644 --- a/srml/sudo/src/lib.rs +++ b/srml/sudo/src/lib.rs @@ -59,7 +59,6 @@ decl_module! { } decl_event!( - /// An event in this module. pub enum Event where AccountId = ::AccountId { /// A sudo just took place. Sudid(bool), diff --git a/srml/support/src/event.rs b/srml/support/src/event.rs index 4ffa552168d30..f83e551183a3c 100644 --- a/srml/support/src/event.rs +++ b/srml/support/src/event.rs @@ -144,6 +144,8 @@ macro_rules! decl_event { // Workaround for https://github.com/rust-lang/rust/issues/26925 . Remove when sorted. #[derive(Clone, PartialEq, Eq, $crate::codec::Encode, $crate::codec::Decode)] #[cfg_attr(feature = "std", derive(Debug))] + /// Events for this module. + /// $(#[$attr])* pub enum Event { $( @@ -277,9 +279,12 @@ macro_rules! __decl_generic_event { /// [`RawEvent`]: enum.RawEvent.html /// [`Trait`]: trait.Trait.html pub type Event<$event_generic_param $(, $instance $( = $event_default_instance)? )?> = RawEvent<$( $generic_type ),* $(, $instance)? >; + // Workaround for https://github.com/rust-lang/rust/issues/26925 . Remove when sorted. #[derive(Clone, PartialEq, Eq, $crate::codec::Encode, $crate::codec::Decode)] #[cfg_attr(feature = "std", derive(Debug))] + /// Events for this module. + /// $(#[$attr])* pub enum RawEvent<$( $generic_param ),* $(, $instance)? > { $( diff --git a/srml/system/src/lib.rs b/srml/system/src/lib.rs index b8d2ff0268a22..7b79aaa3f079c 100644 --- a/srml/system/src/lib.rs +++ b/srml/system/src/lib.rs @@ -125,7 +125,6 @@ pub struct EventRecord { } decl_event!( - /// Event for the system module. pub enum Event { /// An extrinsic completed successfully. ExtrinsicSuccess, diff --git a/srml/treasury/src/lib.rs b/srml/treasury/src/lib.rs index 2d9a0343c3415..09c44e42a7b56 100644 --- a/srml/treasury/src/lib.rs +++ b/srml/treasury/src/lib.rs @@ -170,7 +170,6 @@ decl_storage! { } decl_event!( - /// An event in this module. pub enum Event where Balance = BalanceOf, From 313d06aa4bbc4b33eb65b2ffecf62b6cf65e8077 Mon Sep 17 00:00:00 2001 From: thiolliere Date: Fri, 22 Mar 2019 16:49:24 +0100 Subject: [PATCH 4/6] some missed ones --- node-template/runtime/src/template.rs | 1 - srml/council/src/seats.rs | 1 - srml/democracy/src/lib.rs | 1 - 3 files changed, 3 deletions(-) diff --git a/node-template/runtime/src/template.rs b/node-template/runtime/src/template.rs index 10f8b1eb1382d..9ca372c1f2eba 100644 --- a/node-template/runtime/src/template.rs +++ b/node-template/runtime/src/template.rs @@ -55,7 +55,6 @@ decl_module! { } decl_event!( - /// An event in this module. pub enum Event where AccountId = ::AccountId { // Just a dummy event. // Event `Something` is declared with a parameter of the type `u32` and `AccountId` diff --git a/srml/council/src/seats.rs b/srml/council/src/seats.rs index 365214f32793f..210603b9f4a67 100644 --- a/srml/council/src/seats.rs +++ b/srml/council/src/seats.rs @@ -382,7 +382,6 @@ decl_storage! { } decl_event!( - /// An event in this module. pub enum Event where ::AccountId { /// reaped voter, reaper VoterReaped(AccountId, AccountId), diff --git a/srml/democracy/src/lib.rs b/srml/democracy/src/lib.rs index eb0502ccd9b08..767018f60c01d 100644 --- a/srml/democracy/src/lib.rs +++ b/srml/democracy/src/lib.rs @@ -242,7 +242,6 @@ decl_storage! { } decl_event!( - /// An event in this module. pub enum Event where Balance = BalanceOf, ::AccountId { Proposed(PropIndex, Balance), Tabled(PropIndex, Balance, Vec), From 1f21055b14a564cacadf4b769596047a993c76e4 Mon Sep 17 00:00:00 2001 From: joe petrowski <25483142+joepetrowski@users.noreply.github.com> Date: Mon, 25 Mar 2019 11:18:13 +0100 Subject: [PATCH 5/6] Update srml/example/src/lib.rs Co-Authored-By: thiolliere --- srml/example/src/lib.rs | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/srml/example/src/lib.rs b/srml/example/src/lib.rs index 1e24996f497aa..739ae1ad74d37 100644 --- a/srml/example/src/lib.rs +++ b/srml/example/src/lib.rs @@ -73,7 +73,7 @@ decl_storage! { } decl_event!( - /// Events are simple means of reporting specific conditions and + /// Events are a simple means of reporting specific conditions and /// circumstances that have happened that users, Dapps and/or chain explorers would find /// interesting and otherwise difficult to detect. pub enum Event where B = ::Balance { From df3b4833da66ef42099d9e3827d12b7f497d54c6 Mon Sep 17 00:00:00 2001 From: thiolliere Date: Mon, 25 Mar 2019 11:34:01 +0100 Subject: [PATCH 6/6] Update srml/support/procedural/src/storage/transformation.rs --- srml/support/procedural/src/storage/transformation.rs | 4 +++- 1 file changed, 3 insertions(+), 1 deletion(-) diff --git a/srml/support/procedural/src/storage/transformation.rs b/srml/support/procedural/src/storage/transformation.rs index e394b8070cf0f..2dd323c4f3764 100644 --- a/srml/support/procedural/src/storage/transformation.rs +++ b/srml/support/procedural/src/storage/transformation.rs @@ -500,7 +500,9 @@ fn decl_storage_items( } impls.extend(quote! { - /// Instance trait implemented by all usable instance of the module. + /// Tag a type as an instance of a module. + /// + /// Defines storage prefixes, they must be unique. pub trait #instantiable: 'static { #const_impls }