Cleanup rustdoc (#1965)

* Hide `__GetByteStruct*` types in the docs

* Forward documentation to `GenesisConfig`

* Hide `PhantomItem` in docs for `Call`

* Hide public calls in `Module`

* Forward documenation for storage functions

* Hide auxiliary functions in documentation

substrate/srml/staking/src/lib.rs

@@ -211,12 +211,12 @@ decl_storage! {
 		pub Payee get(payee): map T::AccountId => RewardDestination;
 
 		/// The set of keys are all controllers that want to validate.
-		/// 
+		///
 		/// The values are the preferences that a validator has.
 		pub Validators get(validators): linked_map T::AccountId => ValidatorPrefs<BalanceOf<T>>;
 
 		/// The set of keys are all controllers that want to nominate.
-		/// 
+		///
 		/// The value are the nominations.
 		pub Nominators get(nominators): linked_map T::AccountId => Vec<T::AccountId>;
 
@@ -227,7 +227,7 @@ decl_storage! {
 		// The historical validators and their nominations for a given era. Stored as a trie root of the mapping
 		// `T::AccountId` => `Exposure<T::AccountId, BalanceOf<T>>`, which is just the contents of `Stakers`,
 		// under a key that is the `era`.
-		// 
+		//
 		// Every era change, this will be appended with the trie root of the contents of `Stakers`, and the oldest
 		// entry removed down to a specific number of entries (probably around 90 for a 3 month history).
 //		pub HistoricalStakers get(historical_stakers): map T::BlockNumber => Option<H256>;
@@ -276,7 +276,7 @@ decl_storage! {
 				<Module<T>>::select_validators();
 			});
 		});
-	}	
+	}
 }
 
 decl_module! {
@@ -307,9 +307,9 @@ decl_module! {
 
 		/// Add some extra amount that have appeared in the stash `free_balance` into the balance up for
 		/// staking.
-		/// 
+		///
 		/// Use this if there are additional funds in your stash account that you wish to bond.
-		/// 
+		///
 		/// NOTE: This call must be made by the controller, not the stash.
 		fn bond_extra(origin, max_additional: BalanceOf<T>) {
 			let controller = ensure_signed(origin)?;
@@ -325,15 +325,15 @@ decl_module! {
 		}
 
 		/// Schedule a portion of the stash to be unlocked ready for transfer out after the bond
-		/// period ends. If this leaves an amount actively bonded less than 
+		/// period ends. If this leaves an amount actively bonded less than
 		/// T::Currency::existential_deposit(), then it is increased to the full amount.
-		/// 
+		///
 		/// Once the unlock period is done, you can call `withdraw_unbonded` to actually move
-		/// the funds out of management ready for transfer. 
+		/// the funds out of management ready for transfer.
-		/// 
+		///
 		/// NOTE: This call must be made by the controller, not the stash.
-		/// 
+		///
-		/// See also `withdraw_unbonded`.
+		/// See also [`Call::withdraw_unbonded`].
 		fn unbond(origin, #[compact] value: BalanceOf<T>) {
 			let controller = ensure_signed(origin)?;
 			let mut ledger = Self::ledger(&controller).ok_or("not a controller")?;
@@ -357,13 +357,13 @@ decl_module! {
 		}
 
 		/// Remove any unlocked chunks from the `unlocking` queue from our management.
-		/// 
+		///
 		/// This essentially frees up that balance to be used by the stash account to do
 		/// whatever it wants.
-		/// 
+		///
 		/// NOTE: This call must be made by the controller, not the stash.
-		/// 
+		///
-		/// See also `unbond`.
+		/// See also [`Call::unbond`].
 		fn withdraw_unbonded(origin) {
 			let controller = ensure_signed(origin)?;
 			let ledger = Self::ledger(&controller).ok_or("not a controller")?;
@@ -374,7 +374,7 @@ decl_module! {
 		/// Declare the desire to validate for the origin controller.
 		///
 		/// Effects will be felt at the beginning of the next era.
-		/// 
+		///
 		/// NOTE: This call must be made by the controller, not the stash.
 		fn validate(origin, prefs: ValidatorPrefs<BalanceOf<T>>) {
 			let controller = ensure_signed(origin)?;
@@ -387,7 +387,7 @@ decl_module! {
 		/// Declare the desire to nominate `targets` for the origin controller.
 		///
 		/// Effects will be felt at the beginning of the next era.
-		/// 
+		///
 		/// NOTE: This call must be made by the controller, not the stash.
 		fn nominate(origin, targets: Vec<<T::Lookup as StaticLookup>::Source>) {
 			let controller = ensure_signed(origin)?;
@@ -405,7 +405,7 @@ decl_module! {
 		/// Declare no desire to either validate or nominate.
 		///
 		/// Effects will be felt at the beginning of the next era.
-		/// 
+		///
 		/// NOTE: This call must be made by the controller, not the stash.
 		fn chill(origin) {
 			let controller = ensure_signed(origin)?;
@@ -417,7 +417,7 @@ decl_module! {
 		/// (Re-)set the payment target for a controller.
 		///
 		/// Effects will be felt at the beginning of the next era.
-		/// 
+		///
 		/// NOTE: This call must be made by the controller, not the stash.
 		fn set_payee(origin, payee: RewardDestination) {
 			let controller = ensure_signed(origin)?;
@@ -548,7 +548,7 @@ impl<T: Trait> Module<T> {
 					let _ = T::Currency::reward(&l.stash, amount);
 					Self::update_ledger(who, l);
 				},
-		}		
+		}
 	}
 
 	/// Reward a given validator by a specific amount. Add the reward to their, and their nominators'
@@ -639,7 +639,7 @@ impl<T: Trait> Module<T> {
 	/// @returns the new SlotStake value.
 	fn select_validators() -> BalanceOf<T> {
 		// Map of (would-be) validator account to amount of stake backing it.
-		
+
 		// First, we pull all validators, together with their stash balance into a Vec (cpu=O(V), mem=O(V))
 		let mut candidates = <Validators<T>>::enumerate()
 			.map(|(who, _)| {
@@ -763,7 +763,7 @@ impl<T: Trait> Module<T> {
 			let _ = Self::slash_validator(&v, slash);
 			<Validators<T>>::remove(&v);
 			let _ = Self::apply_force_new_era(false);
-			
+
 			RawEvent::OfflineSlash(v.clone(), slash)
 		} else {
 			RawEvent::OfflineWarning(v.clone(), slash_count)

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

@@ -130,18 +130,20 @@ pub fn decl_storage_impl(input: TokenStream) -> TokenStream {
 		}
 		impl<#traitinstance: 'static + #traittype> #module_ident<#traitinstance> {
 			#impl_store_fns
+			#[doc(hidden)]
 			pub fn store_metadata() -> #scrate::storage::generator::StorageMetadata {
 				#scrate::storage::generator::StorageMetadata {
 					functions: #scrate::storage::generator::DecodeDifferent::Encode(#store_functions_to_metadata) ,
 				}
 			}
+			#[doc(hidden)]
 			pub fn store_metadata_functions() -> &'static [#scrate::storage::generator::StorageFunctionMetadata] {
 				#store_functions_to_metadata
 			}
+			#[doc(hidden)]
 			pub fn store_metadata_name() -> &'static str {
 				#cratename_string
 			}
-
 		}
 
 		#extra_genesis
@@ -168,6 +170,7 @@ fn decl_store_extra_genesis(
 	for sline in storage_lines.inner.iter() {
 
 		let DeclStorageLine {
+			attrs,
 			name,
 			getter,
 			config,
@@ -188,7 +191,13 @@ fn decl_store_extra_genesis(
 				let ident = &getter.getfn.content;
 				quote!( #ident )
 			} else {
-				return Err(syn::Error::new_spanned(name, format!("Invalid storage definiton, couldn't find config identifier: storage must either have a get identifier `get(ident)` or a defined config identifier `config(ident)`")));
+				return Err(
+					Error::new_spanned(
+						name,
+						"Invalid storage definiton, couldn't find config identifier: storage must either have a get identifier \
+						`get(ident)` or a defined config identifier `config(ident)`"
+					)
+				);
 			};
 			if type_infos.kind.is_simple() && ext::has_parametric_type(type_infos.value_type, traitinstance) {
 				is_trait_needed = true;
@@ -199,13 +208,17 @@ fn decl_store_extra_genesis(
 			if let DeclStorageTypeInfosKind::Map { key_type, .. } = type_infos.kind {
 				serde_complete_bound.insert(key_type);
 			}
+
+			// Propagate doc attributes.
+			let attrs = attrs.inner.iter().filter_map(|a| a.parse_meta().ok()).filter(|m| m.name() == "doc");
+
 			let storage_type = type_infos.typ.clone();
 			config_field.extend(match type_infos.kind {
 				DeclStorageTypeInfosKind::Simple => {
-					quote!( pub #ident: #storage_type, )
+					quote!( #( #[ #attrs ] )* pub #ident: #storage_type, )
 				},
 				DeclStorageTypeInfosKind::Map {key_type, .. } => {
-					quote!( pub #ident: Vec<(#key_type, #storage_type)>, )
+					quote!( #( #[ #attrs ] )* pub #ident: Vec<(#key_type, #storage_type)>, )
 				},
 			});
 			opt_build = Some(build.as_ref().map(|b| &b.expr.content).map(|b|quote!( #b ))
@@ -234,7 +247,7 @@ fn decl_store_extra_genesis(
 
 						let v = (#builder)(&self);
 						<#name<#traitinstance> as #scrate::storage::generator::StorageValue<#typ>>::put(&v, &storage);
-						
+
 					}}
 				},
 				DeclStorageTypeInfosKind::Map { key_type, .. } => {
@@ -475,8 +488,12 @@ fn impl_store_items(
 ) -> TokenStream2 {
 	storage_lines.inner.iter().map(|sline| &sline.name)
 		.fold(TokenStream2::new(), |mut items, name| {
-		items.extend(quote!(type #name = #name<#traitinstance>;));
+			items.extend(
-		items
+				quote!(
+					type #name = #name<#traitinstance>;
+				)
+			);
+			items
 	})
 }
 
@@ -488,6 +505,7 @@ fn impl_store_fns(
 	let mut items = TokenStream2::new();
 	for sline in storage_lines.inner.iter() {
 		let DeclStorageLine {
+			attrs,
 			name,
 			getter,
 			storage_type,
@@ -500,10 +518,14 @@ fn impl_store_fns(
 			let type_infos = get_type_infos(storage_type);
 			let value_type = type_infos.value_type;
 
+			// Propagate doc attributes.
+			let attrs = attrs.inner.iter().filter_map(|a| a.parse_meta().ok()).filter(|m| m.name() == "doc");
+
 			let typ = type_infos.typ;
 			let item = match type_infos.kind {
 				DeclStorageTypeInfosKind::Simple => {
 					quote!{
+						#( #[ #attrs ] )*
 						pub fn #get_fn() -> #value_type {
 							<#name<#traitinstance> as #scrate::storage::generator::StorageValue<#typ>> :: get(&#scrate::storage::RuntimeStorage)
 						}
@@ -511,6 +533,7 @@ fn impl_store_fns(
 				},
 				DeclStorageTypeInfosKind::Map { key_type, .. } => {
 					quote!{
+						#( #[ #attrs ] )*
 						pub fn #get_fn<K: #scrate::storage::generator::Borrow<#key_type>>(key: K) -> #value_type {
 							<#name<#traitinstance> as #scrate::storage::generator::StorageMap<#key_type, #typ>> :: get(key.borrow(), &#scrate::storage::RuntimeStorage)
 						}
@@ -579,7 +602,7 @@ fn store_functions_to_metadata (
 			})
 			.unwrap_or_else(|| quote!( Default::default() ));
 		let mut docs = TokenStream2::new();
-		for attr in attrs.inner.iter().filter_map(|v| v.interpret_meta()) {
+		for attr in attrs.inner.iter().filter_map(|v| v.parse_meta().ok()) {
 			if let syn::Meta::NameValue(syn::MetaNameValue{
 				ref ident,
 				ref lit,
@@ -608,6 +631,7 @@ fn store_functions_to_metadata (
 		};
 		items.extend(item);
 		let def_get = quote! {
+			#[doc(hidden)]
 			pub struct #struct_name<#traitinstance>(pub #scrate::rstd::marker::PhantomData<#traitinstance>);
 			#[cfg(feature = "std")]
 			#[allow(non_upper_case_globals)]

substrate/srml/support/src/dispatch.rs

@@ -487,6 +487,7 @@ macro_rules! decl_module {
 		$vis:vis fn $name:ident ( root $(, $param:ident : $param_ty:ty )* ) { $( $impl:tt )* }
 	) => {
 		impl<$trait_instance: $trait_name> $module<$trait_instance> {
+			#[doc(hidden)]
 			$vis fn $name($( $param: $param_ty ),* ) -> $crate::dispatch::Result {
 				{ $( $impl )* }
 				Ok(())
@@ -503,6 +504,7 @@ macro_rules! decl_module {
 		) -> $result:ty { $( $impl:tt )* }
 	) => {
 		impl<$trait_instance: $trait_name> $module<$trait_instance> {
+			#[doc(hidden)]
 			$vis fn $name($( $param: $param_ty ),* ) -> $result {
 				$( $impl )*
 			}
@@ -518,6 +520,7 @@ macro_rules! decl_module {
 		) { $( $impl:tt )* }
 	) => {
 		impl<$trait_instance: $trait_name> $module<$trait_instance> {
+			#[doc(hidden)]
 			$vis fn $name(
 				$origin: $origin_ty $(, $param: $param_ty )*
 			) -> $crate::dispatch::Result {
@@ -608,10 +611,11 @@ macro_rules! decl_module {
 		#[cfg(feature = "std")]
 		$(#[$attr])*
 		pub enum $call_type<$trait_instance: $trait_name> {
+			#[doc(hidden)]
 			__PhantomItem(::std::marker::PhantomData<$trait_instance>),
-			__OtherPhantomItem(::std::marker::PhantomData<$trait_instance>),
 			$(
 				#[allow(non_camel_case_types)]
+				$(#[doc = $doc_attr])*
 				$fn_name ( $( $param ),* ),
 			)*
 		}
@@ -619,10 +623,11 @@ macro_rules! decl_module {
 		#[cfg(not(feature = "std"))]
 		$(#[$attr])*
 		pub enum $call_type<$trait_instance: $trait_name> {
+			#[doc(hidden)]
 			__PhantomItem(::core::marker::PhantomData<$trait_instance>),
-			__OtherPhantomItem(::core::marker::PhantomData<$trait_instance>),
 			$(
 				#[allow(non_camel_case_types)]
+				$(#[doc = $doc_attr])*
 				$fn_name ( $( $param ),* ),
 			)*
 		}
@@ -655,7 +660,6 @@ macro_rules! decl_module {
 							} else {
 								match *_other {
 									$call_type::__PhantomItem(_) => unreachable!(),
-									$call_type::__OtherPhantomItem(_) => unreachable!(),
 									_ => false,
 								}
 							}
@@ -698,7 +702,6 @@ macro_rules! decl_module {
 			fn encode_to<W: $crate::dispatch::Output>(&self, _dest: &mut W) {
 				$crate::__impl_encode!(_dest; *self; 0; $call_type; $( fn $fn_name( $( $(#[$codec_attr on type $param])* $param_name ),* ); )*);
 				if let $call_type::__PhantomItem(_) = *self { unreachable!() }
-				if let $call_type::__OtherPhantomItem(_) = *self { unreachable!() }
 			}
 		}
 		impl<$trait_instance: $trait_name> $crate::dispatch::Dispatchable
@@ -717,7 +720,7 @@ macro_rules! decl_module {
 							)
 						},
 					)*
-					_ => { panic!("__PhantomItem should never be used.") },
+					$call_type::__PhantomItem(_) => { panic!("__PhantomItem should never be used.") },
 				}
 			}
 		}
@@ -728,6 +731,7 @@ macro_rules! decl_module {
 		}
 
 		impl<$trait_instance: $trait_name> $mod_type<$trait_instance> {
+			#[doc(hidden)]
 			pub fn dispatch<D: $crate::dispatch::Dispatchable<Trait = $trait_instance>>(d: D, origin: D::Origin) -> $crate::dispatch::Result {
 				d.dispatch(origin)
 			}
@@ -944,6 +948,7 @@ macro_rules! __dispatch_impl_metadata {
 		$($rest:tt)*
 	) => {
 		impl<$trait_instance: $trait_name> $mod_type<$trait_instance> {
+			#[doc(hidden)]
 			pub fn call_functions() -> &'static [$crate::dispatch::FunctionMetadata] {
 				$crate::__call_to_functions!($($rest)*)
 			}