Clarify and expand ProvideInherent docs

primitives/inherents/src/lib.rs

@@ -398,9 +398,9 @@ impl<E: codec::Encode> IsFatalError for MakeFatalError<E> {
 	}
 }
 
-/// A module that provides an inherent and may also verifies it.
+/// A pallet that provides an inherent and may, optionally, verify it.
 pub trait ProvideInherent {
-	/// The call type of the module.
+	/// The call type of the pallet.
 	type Call;
 	/// The error returned by `check_inherent`.
 	type Error: codec::Encode + IsFatalError;
@@ -410,13 +410,19 @@ pub trait ProvideInherent {
 	/// Create an inherent out of the given `InherentData`.
 	fn create_inherent(data: &InherentData) -> Option<Self::Call>;
 
-	/// If `Some`, indicates that an inherent is required. Check will return the inner error if no
-	/// inherent is found. If `Err`, indicates that the check failed and further operations should
-	/// be aborted.
+	/// Determines whether this inherent is required in this block.
+	/// Ok(None) indicates that this inherent is not required in this block. The default implementation returns this.
+	/// Ok(Some(e)) indicates that this inherent is required in this block, and a call to `check_inherent`
+	/// should return `e` when the inherent is not present.
+	/// Err(_) indicates that this function failed and further operations should be aborted.
 	fn is_inherent_required(_: &InherentData) -> Result<Option<Self::Error>, Self::Error> { Ok(None) }
 
-	/// Check the given inherent if it is valid.
-	/// Checking the inherent is optional and can be omitted.
+	/// Check whether the given inherent is valid. Checking the inherent is optional and can be
+	/// omitted by using the default implementation.
+	///
+	/// When checking an inherent, the first parameter represents the inherent that is actually
+	/// included in the block by its author. whereas the second parameter represents the inherent
+	/// data that the verifying node calculates.
 	fn check_inherent(_: &Self::Call, _: &InherentData) -> Result<(), Self::Error> {
 		Ok(())
 	}