Make Dispatchable return the actual weight consumed (#5458)

* Make Dispatchable return the actual weight consumed

Add PostInfo associated type to Dispatchable and have frame implement
Dispatchable { type PostInfo = PostDispatchInfo } where PostDispatchInfo
contains the actual weight consumed.

* Fix whitespace issues in docs

substrate/primitives/runtime/src/lib.rs

@@ -353,10 +353,15 @@ impl From<DispatchError> for DispatchOutcome {
 	}
 }
 
-/// Result of a module function call; either nothing (functions are only called for "side effects")
-/// or an error message.
+/// This is the legacy return type of `Dispatchable`. It is still exposed for compatibilty
+/// reasons. The new return type is `DispatchResultWithInfo`.
+/// FRAME runtimes should use frame_support::dispatch::DispatchResult
 pub type DispatchResult = sp_std::result::Result<(), DispatchError>;
 
+/// Return type of a `Dispatchable` which contains the `DispatchResult` and additional information
+/// about the `Dispatchable` that is only known post dispatch.
+pub type DispatchResultWithInfo<T> = sp_std::result::Result<T, DispatchErrorWithPostInfo<T>>;
+
 /// Reason why a dispatch call failed
 #[derive(Eq, PartialEq, Clone, Copy, Encode, Decode, RuntimeDebug)]
 #[cfg_attr(feature = "std", derive(Serialize))]
@@ -379,6 +384,18 @@ pub enum DispatchError {
 	},
 }
 
+/// Result of a `Dispatchable` which contains the `DispatchResult` and additional information
+/// about the `Dispatchable` that is only known post dispatch.
+#[derive(Eq, PartialEq, Clone, Copy, Encode, Decode, RuntimeDebug)]
+pub struct DispatchErrorWithPostInfo<Info> where
+	Info: Eq + PartialEq + Clone + Copy + Encode + Decode + traits::Printable
+{
+	/// Addditional information about the `Dispatchable` which is only known post dispatch.
+	pub post_info: Info,
+	/// The actual `DispatchResult` indicating whether the dispatch was succesfull.
+	pub error: DispatchError,
+}
+
 impl DispatchError {
 	/// Return the same error but without the attached message.
 	pub fn stripped(self) -> Self {
@@ -390,6 +407,18 @@ impl DispatchError {
 	}
 }
 
+impl<T, E> From<E> for DispatchErrorWithPostInfo<T> where
+	T: Eq + PartialEq + Clone + Copy + Encode + Decode + traits::Printable + Default,
+	E: Into<DispatchError>
+{
+	fn from(error: E) -> Self {
+		Self {
+			post_info: Default::default(),
+			error: error.into(),
+		}
+	}
+}
+
 impl From<crate::traits::LookupError> for DispatchError {
 	fn from(_: crate::traits::LookupError) -> Self {
 		Self::CannotLookup
@@ -419,6 +448,14 @@ impl From<DispatchError> for &'static str {
 	}
 }
 
+impl<T> From<DispatchErrorWithPostInfo<T>> for &'static str where
+	T: Eq + PartialEq + Clone + Copy + Encode + Decode + traits::Printable
+{
+	fn from(err: DispatchErrorWithPostInfo<T>) -> &'static str {
+		err.error.into()
+	}
+}
+
 impl traits::Printable for DispatchError {
 	fn print(&self) {
 		"DispatchError".print();
@@ -437,6 +474,16 @@ impl traits::Printable for DispatchError {
 	}
 }
 
+impl<T> traits::Printable for DispatchErrorWithPostInfo<T> where
+	T: Eq + PartialEq + Clone + Copy + Encode + Decode + traits::Printable
+{
+	fn print(&self) {
+		self.error.print();
+		"PostInfo: ".print();
+		self.post_info.print();
+	}
+}
+
 /// This type specifies the outcome of dispatching a call to a module.
 ///
 /// In case of failure an error specific to the module is returned.