Docs only changes (#9258)

* Docs changes to improve clarity

Co-authored-by: Bastian Köcher <bkchr@users.noreply.github.com>

Co-authored-by: Guillaume Thiolliere <gui.thiolliere@gmail.com>

substrate/client/transaction-pool/README.md

@@ -79,12 +79,15 @@ Field-specific rules are described below.
 ### `requires` / `provides`
 
 These two fields contain a set of `TransactionTag`s (opaque blobs) associated with
-given transaction. Looking at these fields we can find dependencies between
-transactions and their readiness for block inclusion.
+a given transaction. This is a mechanism for the runtime to be able to
+express dependencies between transactions (that this transaction pool can take
+account of). By looking at these fields we can establish a transaction's readiness
+for block inclusion.
 
 The `provides` set contains properties that will be *satisfied* in case the transaction
-is successfully added to a block. `requires` contains properties that must be satisfied
-**before** the transaction can be included to a block.
+is successfully added to a block. Only a transaction in a block may provide a specific
+tag. `requires` contains properties that must be satisfied **before** the transaction
+can be included to a block.
 
 Note that a transaction with empty `requires` set can be added to a block immediately,
 there are no other transactions that it expects to be included before.
@@ -131,7 +134,7 @@ Transaction priority describes importance of the transaction relative to other t
 in the pool. Block authors can expect benefiting from including such transactions
 before others.
 
-Note that we can't simply order transactions in the pool by `priority`, cause first
+Note that we can't simply order transactions in the pool by `priority`, because first
 we need to make sure that all of the transaction requirements are satisfied (see
 `requires/provides` section). However if we consider a set of transactions
 which all have their requirements (tags) satisfied, the block author should be
@@ -234,7 +237,7 @@ feasible, so the actual implementation might need to take some shortcuts.
 ## Suggestions & caveats
 
 1. The validity of transaction should not change significantly from block to
-   block. I.e. changes in validity should happen predicatably, e.g. `longevity`
+   block. I.e. changes in validity should happen predictably, e.g. `longevity`
    decrements by 1, `priority` stays the same, `requires` changes if transaction
    that provided a tag was included in block. `provides` does not change, etc.
 
@@ -360,5 +363,5 @@ queue and attempted to be re-imported by the background task in the future.
 
 Runtime calls to verify transactions are performed from a separate (limited)
 thread pool to avoid interferring too much with other subsystems of the node. We
-definitely don't want to have all cores validating network transactions, cause
+definitely don't want to have all cores validating network transactions, because
 all of these transactions need to be considered untrusted (potentially DoS).

substrate/client/transaction-pool/graph/src/ready.rs

@@ -108,11 +108,13 @@ Hence every hash retrieved from `provided_tags` is always present in `ready`;
 qed
 "#;
 
+/// Validated transactions that are block ready with all their dependencies met.
 #[derive(Debug, parity_util_mem::MallocSizeOf)]
 pub struct ReadyTransactions<Hash: hash::Hash + Eq, Ex> {
-	/// Insertion id
+	/// Next free insertion id (used to indicate when a transaction was inserted into the pool).
 	insertion_id: u64,
 	/// tags that are provided by Ready transactions
+	/// (only a single transaction can provide a specific tag)
 	provided_tags: HashMap<Tag, Hash>,
 	/// Transactions that are ready (i.e. don't have any requirements external to the pool)
 	ready: TrackedMap<Hash, ReadyTx<Hash, Ex>>,
@@ -235,7 +237,7 @@ impl<Hash: hash::Hash + Member + Serialize, Ex> ReadyTransactions<Hash, Ex> {
 			.fold(None, f)
 	}
 
-	/// Returns true if given hash is part of the queue.
+	/// Returns true if given transaction is part of the queue.
 	pub fn contains(&self, hash: &Hash) -> bool {
 		self.ready.read().contains_key(hash)
 	}

substrate/client/transaction-pool/graph/src/watcher.rs

@@ -24,10 +24,11 @@ use sp_utils::mpsc::{tracing_unbounded, TracingUnboundedSender, TracingUnbounded
 
 /// Extrinsic watcher.
 ///
-/// Represents a stream of status updates for particular extrinsic.
+/// Represents a stream of status updates for a particular extrinsic.
 #[derive(Debug)]
 pub struct Watcher<H, BH> {
 	receiver: TracingUnboundedReceiver<TransactionStatus<H, BH>>,
+	/// transaction hash of watched extrinsic
 	hash: H,
 }