transaction-pool: Improve transaction status documentation and add helpers (#3215)

This PR improves the transaction status documentation.
- Added doc references for describing the main states
- Extra comment wrt pool ready / future queues
- `FinalityTimeout` no longer describes a lagging finality gadget, it
signals that the maximum number of finality gadgets has been reached

A few helper methods are added to indicate when:
- a final event is generated by the transaction pool for a given event
- a final event is provided, although the transaction might become valid
at a later time and could be re-submitted

The helper methods are used and taken from
https://github.com/paritytech/polkadot-sdk/pull/3079 to help us better
keep it in sync.


cc @paritytech/subxt-team

---------

Signed-off-by: Alexandru Vasile <alexandru.vasile@parity.io>

substrate/client/transaction-pool/api/src/error.rs

@@ -71,6 +71,30 @@ pub enum Error {
 	RejectedFutureTransaction,
 }
 
+impl Error {
+	/// Returns true if the transaction could be re-submitted to the pool in the future.
+	///
+	/// For example, `Error::ImmediatelyDropped` is retriable, because the transaction
+	/// may enter the pool if there is space for it in the future.
+	pub fn is_retriable(&self) -> bool {
+		match self {
+			// An invalid transaction is temporarily banned, however it can
+			// become valid at a later time.
+			Error::TemporarilyBanned |
+			// The pool is full at the moment.
+			Error::ImmediatelyDropped |
+			// The block id is not known to the pool.
+			// The node might be lagging behind, or during a warp sync.
+			Error::InvalidBlockId(_) |
+			// The pool is configured to not accept future transactions.
+			Error::RejectedFutureTransaction => {
+				true
+			}
+			_ => false
+		}
+	}
+}
+
 /// Transaction pool error conversion.
 pub trait IntoPoolError: std::error::Error + Send + Sized + Sync {
 	/// Try to extract original `Error`