Clarify and expand ProvideInherent docs

primitives/inherents/src/lib.rs

@@ -398,9 +398,10 @@ impl<E: codec::Encode> IsFatalError for MakeFatalError<E> {
 	}
 }
 
-/// A module that provides an inherent and may also verifies it.
+/// A pallet that provides or verifies an inherent extrinsic.
+/// The pallet may provide the inherent, verify an inherent, or both provide and verify.
 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 +411,27 @@ 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. The
+	/// `impl_outer_inherent!`, will call this function from its `check_extrinsics`.
+	/// If the inherent is not present, it will return `e`.
+	///
+	/// Err(_) indicates that this function failed and further operations should be aborted.
+	///
+	/// CAUTION: This check has a bug when used in pallets that also provide unsigned transactions.
+	/// See https://github.com/paritytech/substrate/issues/6243 for details.
 	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(())
 	}