improve docs (#2068)

* improve decl_storage instance doc

* use decl_event doc accordignly

* automate doc and while allow to extend it on event

* some missed ones

* Update srml/example/src/lib.rs

Co-Authored-By: thiolliere <gui.thiolliere@gmail.com>

* Update srml/support/procedural/src/storage/transformation.rs

substrate/node-template/runtime/src/template.rs

@@ -55,7 +55,6 @@ decl_module! {
 }
 
 decl_event!(
-	/// An event in this module.
 	pub enum Event<T> where AccountId = <T as system::Trait>::AccountId {
 		// Just a dummy event.
 		// Event `Something` is declared with a parameter of the type `u32` and `AccountId`

substrate/srml/assets/src/lib.rs

@@ -82,9 +82,6 @@ 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!(
 	pub enum Event<T> where <T as system::Trait>::AccountId, <T as Trait>::Balance {
 		/// Some assets were issued.

substrate/srml/council/src/motions.rs

@@ -47,7 +47,6 @@ pub enum Origin {
 	Members(u32),
 }
 
-/// Event for this module.
 decl_event!(
 	pub enum Event<T> where <T as system::Trait>::Hash, <T as system::Trait>::AccountId {
 		/// A motion (given hash) has been proposed (by given account) with a threshold (given u32).

substrate/srml/council/src/seats.rs

@@ -382,7 +382,6 @@ decl_storage! {
 }
 
 decl_event!(
-	/// An event in this module.
 	pub enum Event<T> where <T as system::Trait>::AccountId {
 		/// reaped voter, reaper
 		VoterReaped(AccountId, AccountId),

substrate/srml/council/src/voting.rs

@@ -125,7 +125,6 @@ decl_storage! {
 	}
 }
 
-/// An event in this module.
 decl_event!(
 	pub enum Event<T> where <T as system::Trait>::Hash {
 		/// A voting tally has happened for a referendum cancellation vote.

substrate/srml/democracy/src/lib.rs

@@ -242,7 +242,6 @@ decl_storage! {
 }
 
 decl_event!(
-	/// An event in this module.
 	pub enum Event<T> where Balance = BalanceOf<T>, <T as system::Trait>::AccountId {
 		Proposed(PropIndex, Balance),
 		Tabled(PropIndex, Balance, Vec<AccountId>),

substrate/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!(
+	/// 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<T> where B = <T as balances::Trait>::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.

substrate/srml/grandpa/src/lib.rs

@@ -176,7 +176,6 @@ impl<N: Decode, SessionKey: Decode> Decode for StoredPendingChange<N, SessionKey
 	}
 }
 
-/// GRANDPA events.
 decl_event!(
 	pub enum Event<T> where <T as Trait>::SessionKey {
 		/// New authority set has been applied.

substrate/srml/session/src/lib.rs

@@ -84,7 +84,6 @@ decl_module! {
 	}
 }
 
-/// An event in this module.
 decl_event!(
 	pub enum Event<T> where <T as system::Trait>::BlockNumber {
 		/// New session has happened. Note that the argument is the session index, not the block

substrate/srml/staking/src/lib.rs

@@ -721,7 +721,6 @@ decl_module! {
 	}
 }
 
-// An event in this module.
 decl_event!(
 	pub enum Event<T> where Balance = BalanceOf<T>, <T as system::Trait>::AccountId {
 		/// All validators have been rewarded by the given balance.

substrate/srml/sudo/src/lib.rs

@@ -58,7 +58,6 @@ decl_module! {
 	}
 }
 
-/// An event in this module.
 decl_event!(
 	pub enum Event<T> where AccountId = <T as system::Trait>::AccountId {
 		/// A sudo just took place.

substrate/srml/support/procedural/src/storage/transformation.rs

@@ -500,6 +500,9 @@ fn decl_storage_items(
 			}
 
 			impls.extend(quote! {
+				/// Tag a type as an instance of a module.
+				/// 
+				/// Defines storage prefixes, they must be unique.
 				pub trait #instantiable: 'static {
 					#const_impls
 				}
@@ -510,12 +513,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 +532,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

substrate/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)? > {
 			$(

substrate/srml/treasury/src/lib.rs

@@ -31,11 +31,6 @@ type BalanceOf<T> = <<T as Trait>::Currency as Currency<<T as system::Trait>::Ac
 type PositiveImbalanceOf<T> = <<T as Trait>::Currency as Currency<<T as system::Trait>::AccountId>>::PositiveImbalance;
 type NegativeImbalanceOf<T> = <<T as Trait>::Currency as Currency<<T as system::Trait>::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<Self::AccountId>;
@@ -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<T: Trait> for enum Call where origin: T::Origin {
 		fn deposit_event<T>() = default;
 		/// Put forward a suggestion for spending. A deposit proportional to the value
@@ -177,7 +169,6 @@ decl_storage! {
 	}
 }
 
-/// An event in this module.
 decl_event!(
 	pub enum Event<T>
 	where