Improve documentation for fast-unstake pallet (#14101)

* improve documentation of fast-unstake pallet * using Sam's crate now * fix * remove stuff not needed * Some updates * use new prelude. * update * some other fancy docs * Update frame/fast-unstake/src/lib.rs Co-authored-by: Liam Aharon <liam.aharon@hotmail.com> * Update frame/support/procedural/src/pallet/expand/mod.rs Co-authored-by: Liam Aharon <liam.aharon@hotmail.com> * update * Update frame/fast-unstake/src/lib.rs Co-authored-by: Keith Yeung <kungfukeith11@gmail.com> * update * fix no_std issue by updating to latest version of docify * get things compiling by adding a use for StakingInterface * fix docify paths to their proper values, still not working because bug * embed working 🎉 * update syn * upgrade to docify v0.1.10 for some fixes * Apply suggestions from code review Co-authored-by: Juan <juangirini@gmail.com> Co-authored-by: Gonçalo Pestana <g6pestana@gmail.com> * improve docs * Update frame/support/procedural/src/pallet/expand/doc_only.rs Co-authored-by: Juan <juangirini@gmail.com> * fmt * fix * Update frame/support/procedural/src/pallet/expand/doc_only.rs Co-authored-by: Muharem Ismailov <ismailov.m.h@gmail.com> * Update frame/support/procedural/src/pallet/expand/config.rs Co-authored-by: Muharem Ismailov <ismailov.m.h@gmail.com> * Update frame/support/procedural/src/pallet/expand/config.rs Co-authored-by: Muharem Ismailov <ismailov.m.h@gmail.com> * remove redundant * update docify rev * update. * update. * update lock file --------- Co-authored-by: Liam Aharon <liam.aharon@hotmail.com> Co-authored-by: Keith Yeung <kungfukeith11@gmail.com> Co-authored-by: Sam Johnson <sam@durosoft.com> Co-authored-by: Juan <juangirini@gmail.com> Co-authored-by: Gonçalo Pestana <g6pestana@gmail.com> Co-authored-by: Muharem Ismailov <ismailov.m.h@gmail.com> Co-authored-by: parity-processbot <>
2026-04-30 02:37:58 +00:00 · 2023-05-29 19:44:42 +02:00
parent 50cf22b0bb
commit b8bca85e9d
15 changed files with 378 additions and 121 deletions
@@ -113,7 +113,13 @@ pub fn expand_call(def: &mut Def) -> proc_macro2::TokenStream {
 	}
 	debug_assert_eq!(fn_weight.len(), methods.len());

-	let fn_doc = methods.iter().map(|method| &method.docs).collect::<Vec<_>>();
+	let fn_doc = methods
+		.iter()
+		.map(|method| {
+			let reference = format!("See [`Pallet::{}`].", method.name);
+			quote!(#reference)
+		})
+		.collect::<Vec<_>>();

 	let args_name = methods
 		.iter()
@@ -175,9 +181,8 @@ pub fn expand_call(def: &mut Def) -> proc_macro2::TokenStream {
 			.collect::<Vec<_>>()
 	});

-	let default_docs = [syn::parse_quote!(
-		r"Contains one variant per dispatchable that can be called by an extrinsic."
-	)];
+	let default_docs =
+		[syn::parse_quote!(r"Contains a variant per dispatchable extrinsic that this pallet has.")];
 	let docs = if docs.is_empty() { &default_docs[..] } else { &docs[..] };

 	let maybe_compile_error = if def.call.is_none() {
@@ -274,7 +279,7 @@ pub fn expand_call(def: &mut Def) -> proc_macro2::TokenStream {
 				#frame_support::Never,
 			),
 			#(
-				#( #[doc = #fn_doc] )*
+				#[doc = #fn_doc]
 				#[codec(index = #call_index)]
 				#fn_name {
 					#(
@@ -16,7 +16,6 @@
 // limitations under the License.

 use crate::pallet::Def;
-use frame_support_procedural_tools::get_doc_literals;

 ///
 /// * Generate default rust doc
@@ -31,15 +30,19 @@ pub fn expand_config(def: &mut Def) -> proc_macro2::TokenStream {
 		}
 	};

-	if get_doc_literals(&config_item.attrs).is_empty() {
-		config_item.attrs.push(syn::parse_quote!(
-			#[doc = r"
-			Configuration trait of this pallet.
+	config_item.attrs.insert(
+		0,
+		syn::parse_quote!(
+			#[doc = r"Configuration trait of this pallet.

-			Implement this type for a runtime in order to customize this pallet.
-			"]
-		));
-	}
+The main purpose of this trait is to act as an interface between this pallet and the runtime in
+which it is embedded in. A type, function, or constant in this trait is essentially left to be
+configured by the runtime that includes this pallet.
+
+Consequently, a runtime that wants to include this pallet must implement this trait."
+			]
+		),
+	);

 	Default::default()
 }
@@ -20,8 +20,6 @@ use proc_macro2::Span;
 use crate::pallet::Def;

 pub fn expand_doc_only(def: &mut Def) -> proc_macro2::TokenStream {
-	let storage_names = def.storages.iter().map(|storage| &storage.ident);
-	let storage_docs = def.storages.iter().map(|storage| &storage.docs);
 	let dispatchables = if let Some(call_def) = &def.call {
 		let type_impl_generics = def.type_impl_generics(Span::call_site());
 		call_def
@@ -35,17 +33,16 @@ pub fn expand_doc_only(def: &mut Def) -> proc_macro2::TokenStream {
 					.map(|(_, arg_name, arg_type)| quote::quote!( #arg_name: #arg_type, ))
 					.collect::<proc_macro2::TokenStream>();
 				let docs = &method.docs;
-				let line_2 =
-					format!(" designed to document the [`{}`][`Call::{}`] variant of", name, name);
+
+				let real = format!(" [`Pallet::{}`].", name);
 				quote::quote!(
 					#( #[doc = #docs] )*
 					///
-					/// ---
+					/// # Warning: Doc-Only
 					///
-					/// NOTE: This function is an automatically generated, doc only, uncallable stub.
-					#[ doc = #line_2 ]
-					/// the pallet [`Call`] enum. You should not attempt to call this function
-					/// directly.
+					/// This function is an automatically generated, and is doc-only, uncallable
+					/// stub. See the real version in
+					#[ doc = #real ]
 					pub fn #name<#type_impl_generics>(#args) { unreachable!(); }
 				)
 			})
@@ -54,22 +51,49 @@ pub fn expand_doc_only(def: &mut Def) -> proc_macro2::TokenStream {
 		quote::quote!()
 	};

+	let storage_types = def
+		.storages
+		.iter()
+		.map(|storage| {
+			let storage_name = &storage.ident;
+			let storage_type_docs = &storage.docs;
+			let real = format!("[`pallet::{}`].", storage_name);
+			quote::quote!(
+				#( #[doc = #storage_type_docs] )*
+				///
+				/// # Warning: Doc-Only
+				///
+				/// This type is automatically generated, and is doc-only. See the real version in
+				#[ doc = #real ]
+				pub struct #storage_name();
+			)
+		})
+		.collect::<proc_macro2::TokenStream>();
+
 	quote::quote!(
-		/// Auto-generated docs-only module listing all defined storage types for this pallet.
-		/// Note that members of this module cannot be used directly and are only provided for
-		/// documentation purposes.
+		/// Auto-generated docs-only module listing all (public and private) defined storage types
+		/// for this pallet.
+		///
+		/// # Warning: Doc-Only
+		///
+		/// Members of this module cannot be used directly and are only provided for documentation
+		/// purposes.
+		///
+		/// To see the actual storage type, find a struct with the same name at the root of the
+		/// pallet, in the list of [*Type Definitions*](../index.html#types).
 		#[cfg(doc)]
 		pub mod storage_types {
 			use super::*;
-			#(
-				#( #[doc = #storage_docs] )*
-				pub struct #storage_names();
-			)*
+			#storage_types
 		}

 		/// Auto-generated docs-only module listing all defined dispatchables for this pallet.
-		/// Note that members of this module cannot be used directly and are only provided for
-		/// documentation purposes.
+		///
+		/// # Warning: Doc-Only
+		///
+		/// Members of this module cannot be used directly and are only provided for documentation
+		/// purposes. To see the real version of each dispatchable, look for them in [`Pallet`] or
+		/// [`Call`].
 		#[cfg(doc)]
 		pub mod dispatchables {
 			use super::*;
@@ -110,10 +110,7 @@ pub fn expand_error(def: &mut Def) -> proc_macro2::TokenStream {

 	if get_doc_literals(&error_item.attrs).is_empty() {
 		error_item.attrs.push(syn::parse_quote!(
-			#[doc = r"
-			Custom [dispatch errors](https://docs.substrate.io/main-docs/build/events-errors/)
-			of this pallet.
-			"]
+			#[doc = "The `Error` enum of this pallet."]
 		));
 	}

@@ -97,12 +97,9 @@ pub fn expand_event(def: &mut Def) -> proc_macro2::TokenStream {
 	}

 	if get_doc_literals(&event_item.attrs).is_empty() {
-		event_item.attrs.push(syn::parse_quote!(
-			#[doc = r"
-			The [event](https://docs.substrate.io/main-docs/build/events-errors/) emitted
-			by this pallet.
-			"]
-		));
+		event_item
+			.attrs
+			.push(syn::parse_quote!(#[doc = "The `Event` enum of this pallet"]));
 	}

 	// derive some traits because system event require Clone, FullCodec, Eq, PartialEq and Debug
@@ -36,7 +36,6 @@ mod type_value;
 mod validate_unsigned;

 use crate::pallet::Def;
-use frame_support_procedural_tools::get_doc_literals;
 use quote::ToTokens;

 /// Merge where clause together, `where` token span is taken from the first not none one.
@@ -75,16 +74,24 @@ pub fn expand(mut def: Def) -> proc_macro2::TokenStream {
 	let tt_default_parts = tt_default_parts::expand_tt_default_parts(&mut def);
 	let doc_only = doc_only::expand_doc_only(&mut def);

-	if get_doc_literals(&def.item.attrs).is_empty() {
-		def.item.attrs.push(syn::parse_quote!(
-			#[doc = r"
-			The module that hosts all the
-			[FRAME](https://docs.substrate.io/main-docs/build/events-errors/)
-			types needed to add this pallet to a
-			runtime.
-			"]
-		));
-	}
+	def.item.attrs.insert(
+		0,
+		syn::parse_quote!(
+			#[doc = r"The `pallet` module in each FRAME pallet hosts the most important items needed
+to construct this pallet.
+
+The main components of this pallet are:
+- [`Pallet`], which implements all of the dispatchable extrinsics of the pallet, among
+other public functions.
+	- The subset of the functions that are dispatchable can be identified either in the
+	[`dispatchables`] module or in the [`Call`] enum.
+- [`storage_types`], which contains the list of all types that are representing a
+storage item. Otherwise, all storage items are listed among [*Type Definitions*](#types).
+- [`Config`], which contains the configuration trait of this pallet.
+- [`Event`] and [`Error`], which are listed among the [*Enums*](#enums).
+		"]
+		),
+	);

 	let new_items = quote::quote!(
 		#metadata_docs
@@ -62,8 +62,8 @@ pub fn expand_pallet_struct(def: &mut Def) -> proc_macro2::TokenStream {
 	if get_doc_literals(&pallet_item.attrs).is_empty() {
 		pallet_item.attrs.push(syn::parse_quote!(
 			#[doc = r"
-			The [pallet](https://docs.substrate.io/reference/frame-pallets/#pallets) implementing
-			the on-chain logic.
+				The `Pallet` struct, the main type that implements traits and standalone
+				functions within the pallet.
 			"]
 		));
 	}
@@ -22,6 +22,7 @@ use crate::{
 		Def,
 	},
 };
+use itertools::Itertools;
 use quote::ToTokens;
 use std::{collections::HashMap, ops::IndexMut};
 use syn::spanned::Spanned;
@@ -310,6 +311,65 @@ pub fn process_generics(def: &mut Def) -> syn::Result<Vec<ResultOnEmptyStructMet
 	Ok(on_empty_struct_metadata)
 }

+fn augment_final_docs(def: &mut Def) {
+	// expand the docs with a new line showing the storage type (value, map, double map, etc), and
+	// the key/value type(s).
+	let mut push_string_literal = |doc_line: &str, storage: &mut StorageDef| {
+		let item = &mut def.item.content.as_mut().expect("Checked by def").1[storage.index];
+		let typ_item = match item {
+			syn::Item::Type(t) => t,
+			_ => unreachable!("Checked by def"),
+		};
+		typ_item.attrs.push(syn::parse_quote!(#[doc = ""]));
+		typ_item.attrs.push(syn::parse_quote!(#[doc = #doc_line]));
+	};
+	def.storages.iter_mut().for_each(|storage| match &storage.metadata {
+		Metadata::Value { value } => {
+			let doc_line = format!(
+				"Storage type is [`StorageValue`] with value type `{}`.",
+				value.to_token_stream()
+			);
+			push_string_literal(&doc_line, storage);
+		},
+		Metadata::Map { key, value } => {
+			let doc_line = format!(
+				"Storage type is [`StorageMap`] with key type `{}` and value type `{}`.",
+				key.to_token_stream(),
+				value.to_token_stream()
+			);
+			push_string_literal(&doc_line, storage);
+		},
+		Metadata::DoubleMap { key1, key2, value } => {
+			let doc_line = format!(
+				"Storage type is [`StorageDoubleMap`] with key1 type {}, key2 type {} and value type {}.",
+				key1.to_token_stream(),
+				key2.to_token_stream(),
+				value.to_token_stream()
+			);
+			push_string_literal(&doc_line, storage);
+		},
+		Metadata::NMap { keys, value, .. } => {
+			let doc_line = format!(
+				"Storage type is [`StorageNMap`] with keys type ({}) and value type {}.",
+				keys.iter()
+					.map(|k| k.to_token_stream().to_string())
+					.collect::<Vec<_>>()
+					.join(", "),
+				value.to_token_stream()
+			);
+			push_string_literal(&doc_line, storage);
+		},
+		Metadata::CountedMap { key, value } => {
+			let doc_line = format!(
+				"Storage type is [`CountedStorageMap`] with key type {} and value type {}.",
+				key.to_token_stream(),
+				value.to_token_stream()
+			);
+			push_string_literal(&doc_line, storage);
+		},
+	});
+}
+
 ///
 /// * generate StoragePrefix structs (e.g. for a storage `MyStorage` a struct with the name
 ///   `_GeneratedPrefixForStorage$NameOfStorage` is generated) and implements StorageInstance trait.
@@ -323,6 +383,8 @@ pub fn expand_storages(def: &mut Def) -> proc_macro2::TokenStream {
 		Err(e) => return e.into_compile_error(),
 	};

+	augment_final_docs(def);
+
 	// Check for duplicate prefixes
 	let mut prefix_set = HashMap::new();
 	let mut errors = def
@@ -365,10 +427,6 @@ pub fn expand_storages(def: &mut Def) -> proc_macro2::TokenStream {
 		if let Some(getter) = &storage.getter {
 			let completed_where_clause =
 				super::merge_where_clauses(&[&storage.where_clause, &def.config.where_clause]);
-			let docs = storage
-				.docs
-				.iter()
-				.map(|d| quote::quote_spanned!(storage.attr_span => #[doc = #d]));

 			let ident = &storage.ident;
 			let gen = &def.type_use_generics(storage.attr_span);
@@ -378,6 +436,13 @@ pub fn expand_storages(def: &mut Def) -> proc_macro2::TokenStream {

 			let cfg_attrs = &storage.cfg_attrs;

+			// If the storage item is public, just link to it rather than copy-pasting the docs.
+			let getter_doc_line = if matches!(storage.vis, syn::Visibility::Public(_)) {
+				format!("An auto-generated getter for [`{}`].", storage.ident)
+			} else {
+				storage.docs.iter().map(|d| d.into_token_stream().to_string()).join("\n")
+			};
+
 			match &storage.metadata {
 				Metadata::Value { value } => {
 					let query = match storage.query_kind.as_ref().expect("Checked by def") {
@@ -394,7 +459,7 @@ pub fn expand_storages(def: &mut Def) -> proc_macro2::TokenStream {
 					quote::quote_spanned!(storage.attr_span =>
 						#(#cfg_attrs)*
 						impl<#type_impl_gen> #pallet_ident<#type_use_gen> #completed_where_clause {
-							#( #docs )*
+							#[doc = #getter_doc_line]
 							pub fn #getter() -> #query {
 								<
 									#full_ident as #frame_support::storage::StorageValue<#value>
@@ -418,7 +483,7 @@ pub fn expand_storages(def: &mut Def) -> proc_macro2::TokenStream {
 					quote::quote_spanned!(storage.attr_span =>
 						#(#cfg_attrs)*
 						impl<#type_impl_gen> #pallet_ident<#type_use_gen> #completed_where_clause {
-							#( #docs )*
+							#[doc = #getter_doc_line]
 							pub fn #getter<KArg>(k: KArg) -> #query where
 								KArg: #frame_support::codec::EncodeLike<#key>,
 							{
@@ -444,7 +509,7 @@ pub fn expand_storages(def: &mut Def) -> proc_macro2::TokenStream {
 					quote::quote_spanned!(storage.attr_span =>
 						#(#cfg_attrs)*
 						impl<#type_impl_gen> #pallet_ident<#type_use_gen> #completed_where_clause {
-							#( #docs )*
+							#[doc = #getter_doc_line]
 							pub fn #getter<KArg>(k: KArg) -> #query where
 								KArg: #frame_support::codec::EncodeLike<#key>,
 							{
@@ -470,7 +535,7 @@ pub fn expand_storages(def: &mut Def) -> proc_macro2::TokenStream {
 					quote::quote_spanned!(storage.attr_span =>
 						#(#cfg_attrs)*
 						impl<#type_impl_gen> #pallet_ident<#type_use_gen> #completed_where_clause {
-							#( #docs )*
+							#[doc = #getter_doc_line]
 							pub fn #getter<KArg1, KArg2>(k1: KArg1, k2: KArg2) -> #query where
 								KArg1: #frame_support::codec::EncodeLike<#key1>,
 								KArg2: #frame_support::codec::EncodeLike<#key2>,
@@ -498,7 +563,7 @@ pub fn expand_storages(def: &mut Def) -> proc_macro2::TokenStream {
 					quote::quote_spanned!(storage.attr_span =>
 						#(#cfg_attrs)*
 						impl<#type_impl_gen> #pallet_ident<#type_use_gen> #completed_where_clause {
-							#( #docs )*
+							#[doc = #getter_doc_line]
 							pub fn #getter<KArg>(key: KArg) -> #query
 							where
 								KArg: #frame_support::storage::types::EncodeLikeTuple<
@@ -1520,6 +1520,17 @@ pub mod tests {
 	}
 }

+/// Prelude to be used for pallet testing, for ease of use.
+#[cfg(feature = "std")]
+pub mod testing_prelude {
+	pub use super::{
+		assert_err, assert_err_ignore_postinfo, assert_err_with_weight, assert_error_encoded_size,
+		assert_noop, assert_ok, assert_storage_noop, bounded_btree_map, bounded_vec,
+		parameter_types, traits::Get,
+	};
+	pub use sp_arithmetic::assert_eq_error_rate;
+}
+
 /// Prelude to be used alongside pallet macro, for ease of use.
 pub mod pallet_prelude {
 	pub use crate::{
@@ -34,7 +34,7 @@ pub mod pallet {
 	#[pallet::pallet]
 	pub struct Pallet<T>(_);

-	/// The configuration trait
+	/// The configuration trait.
 	#[pallet::config]
 	#[pallet::disable_frame_system_supertrait_check]
 	pub trait Config: 'static + Eq + Clone {