Augmented node template docs (#6721)

substrate/bin/node-template/pallets/template/src/lib.rs

@@ -1,13 +1,8 @@
 #![cfg_attr(not(feature = "std"), no_std)]
 
-/// A FRAME pallet template with necessary imports
-
-/// Feel free to remove or edit this file as needed.
-/// If you change the name of this file, make sure to update its references in runtime/src/lib.rs
-/// If you remove this file, you can remove those references
-
-/// For more guidance on Substrate FRAME, see the example pallet
-/// https://github.com/paritytech/substrate/blob/master/frame/example/src/lib.rs
+/// Edit this file to define custom logic or remove it if it is not needed.
+/// Learn more about FRAME and the core library of Substrate FRAME pallets:
+/// https://substrate.dev/docs/en/knowledgebase/runtime/frame
 
 use frame_support::{decl_module, decl_storage, decl_event, decl_error, dispatch, traits::Get};
 use frame_system::ensure_signed;
@@ -18,89 +13,87 @@ mod mock;
 #[cfg(test)]
 mod tests;
 
-/// The pallet's configuration trait.
+/// Configure the pallet by specifying the parameters and types on which it depends.
 pub trait Trait: frame_system::Trait {
-	// Add other types and constants required to configure this pallet.
-
-	/// The overarching event type.
+	/// Because this pallet emits events, it depends on the runtime's definition of an event.
 	type Event: From<Event<Self>> + Into<<Self as frame_system::Trait>::Event>;
 }
 
-// This pallet's storage items.
+// The pallet's runtime storage items.
+// https://substrate.dev/docs/en/knowledgebase/runtime/storage
 decl_storage! {
-	// It is important to update your storage name so that your pallet's
-	// storage items are isolated from other pallets.
+	// A unique name is used to ensure that the pallet's storage items are isolated.
+	// This name may be updated, but each pallet in the runtime must use a unique name.
 	// ---------------------------------vvvvvvvvvvvvvv
 	trait Store for Module<T: Trait> as TemplateModule {
-		// Just a dummy storage item.
-		// Here we are declaring a StorageValue, `Something` as a Option<u32>
-		// `get(fn something)` is the default getter which returns either the stored `u32` or `None` if nothing stored
+		// Learn more about declaring storage items:
+		// https://substrate.dev/docs/en/knowledgebase/runtime/storage#declaring-storage-items
 		Something get(fn something): Option<u32>;
 	}
 }
 
-// The pallet's events
+// Pallets use events to inform users when important changes are made.
+// https://substrate.dev/docs/en/knowledgebase/runtime/events
 decl_event!(
 	pub enum Event<T> where AccountId = <T as frame_system::Trait>::AccountId {
-		/// Just a dummy event.
-		/// Event `Something` is declared with a parameter of the type `u32` and `AccountId`
-		/// To emit this event, we call the deposit function, from our runtime functions
-		/// [something, who]
+		/// Event documentation should end with an array that provides descriptive names for event
+		/// parameters. [something, who]
 		SomethingStored(u32, AccountId),
 	}
 );
 
-// The pallet's errors
+// Errors inform users that something went wrong.
 decl_error! {
 	pub enum Error for Module<T: Trait> {
-		/// Value was None
+		/// Error names should be descriptive.
 		NoneValue,
-		/// Value reached maximum and cannot be incremented further
+		/// Errors should have helpful documentation associated with them.
 		StorageOverflow,
 	}
 }
 
-// The pallet's dispatchable functions.
+// Dispatchable functions allows users to interact with the pallet and invoke state changes.
+// These functions materialize as "extrinsics", which are often compared to transactions.
+// Dispatchable functions must be annotated with a weight and must return a DispatchResult.
 decl_module! {
-	/// The module declaration.
 	pub struct Module<T: Trait> for enum Call where origin: T::Origin {
-		// Initializing errors
-		// this includes information about your errors in the node's metadata.
-		// it is needed only if you are using errors in your pallet
+		// Errors must be initialized if they are used by the pallet.
 		type Error = Error<T>;
 
-		// Initializing events
-		// this is needed only if you are using events in your pallet
+		// Events must be initialized if they are used by the pallet.
 		fn deposit_event() = default;
 
-		/// Just a dummy entry point.
-		/// function that can be called by the external world as an extrinsics call
-		/// takes a parameter of the type `AccountId`, stores it, and emits an event
+		/// An example dispatchable that takes a singles value as a parameter, writes the value to
+		/// storage and emits an event. This function must be dispatched by a signed extrinsic.
 		#[weight = 10_000 + T::DbWeight::get().writes(1)]
 		pub fn do_something(origin, something: u32) -> dispatch::DispatchResult {
-			// Check it was signed and get the signer. See also: ensure_root and ensure_none
+			// Check that the extrinsic was signed and get the signer.
+			// This function will return an error if the extrinsic is not signed.
+			// https://substrate.dev/docs/en/knowledgebase/runtime/origin
 			let who = ensure_signed(origin)?;
 
-			// Code to execute when something calls this.
-			// For example: the following line stores the passed in u32 in the storage
+			// Update storage.
 			Something::put(something);
 
-			// Here we are raising the Something event
+			// Emit an event.
 			Self::deposit_event(RawEvent::SomethingStored(something, who));
+			// Return a successful DispatchResult
 			Ok(())
 		}
 
-		/// Another dummy entry point.
-		/// takes no parameters, attempts to increment storage value, and possibly throws an error
+		/// An example dispatchable that may throw a custom error.
 		#[weight = 10_000 + T::DbWeight::get().reads_writes(1,1)]
 		pub fn cause_error(origin) -> dispatch::DispatchResult {
-			// Check it was signed and get the signer. See also: ensure_root and ensure_none
 			let _who = ensure_signed(origin)?;
 
+			// Read a value from storage.
 			match Something::get() {
+				// Return an error if the value has not been set.
 				None => Err(Error::<T>::NoneValue)?,
 				Some(old) => {
+					// Increment the value read from storage; will error in the event of overflow.
 					let new = old.checked_add(1).ok_or(Error::<T>::StorageOverflow)?;
+					// Update the value in storage with the incremented result.
 					Something::put(new);
 					Ok(())
 				},

substrate/bin/node-template/pallets/template/src/mock.rs

@@ -1,5 +1,3 @@
-// Creating mock runtime here
-
 use crate::{Module, Trait};
 use sp_core::H256;
 use frame_support::{impl_outer_origin, parameter_types, weights::Weight};
@@ -12,9 +10,8 @@ impl_outer_origin! {
 	pub enum Origin for Test {}
 }
 
-// For testing the pallet, we construct most of a mock runtime. This means
-// first constructing a configuration type (`Test`) which `impl`s each of the
-// configuration traits of pallets we want to use.
+// Configure a mock runtime to test the pallet.
+
 #[derive(Clone, Eq, PartialEq)]
 pub struct Test;
 parameter_types! {
@@ -23,6 +20,7 @@ parameter_types! {
 	pub const MaximumBlockLength: u32 = 2 * 1024;
 	pub const AvailableBlockRatio: Perbill = Perbill::from_percent(75);
 }
+
 impl system::Trait for Test {
 	type BaseCallFilter = ();
 	type Origin = Origin;
@@ -50,13 +48,14 @@ impl system::Trait for Test {
 	type OnKilledAccount = ();
 	type SystemWeightInfo = ();
 }
+
 impl Trait for Test {
 	type Event = ();
 }
+
 pub type TemplateModule = Module<Test>;
 
-// This function basically just builds a genesis storage key/value store according to
-// our desired mockup.
+// Build genesis storage according to the mock runtime.
 pub fn new_test_ext() -> sp_io::TestExternalities {
 	system::GenesisConfig::default().build_storage::<Test>().unwrap().into()
 }

substrate/bin/node-template/pallets/template/src/tests.rs

@@ -1,15 +1,12 @@
-// Tests to be written here
-
 use crate::{Error, mock::*};
 use frame_support::{assert_ok, assert_noop};
 
 #[test]
 fn it_works_for_default_value() {
 	new_test_ext().execute_with(|| {
-		// Just a dummy test for the dummy function `do_something`
-		// calling the `do_something` function with a value 42
+		// Dispatch a signed extrinsic.
 		assert_ok!(TemplateModule::do_something(Origin::signed(1), 42));
-		// asserting that the stored value is equal to what we stored
+		// Read pallet storage and assert an expected result.
 		assert_eq!(TemplateModule::something(), Some(42));
 	});
 }
@@ -17,7 +14,7 @@ fn it_works_for_default_value() {
 #[test]
 fn correct_error_for_none_value() {
 	new_test_ext().execute_with(|| {
-		// Ensure the correct error is thrown on None value
+		// Ensure the expected error is thrown when no value is present.
 		assert_noop!(
 			TemplateModule::cause_error(Origin::signed(1)),
 			Error::<Test>::NoneValue