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,
 }
 

substrate/primitives/transaction-storage-proof/README.md

@@ -1,3 +1,5 @@
-Authorship Primitives
+Transaction Storage Proof Primitives
 
-License: Apache-2.0
+Contains types and basic code to extract storage proofs for indexed transactions.
+
+License: Apache-2.0

substrate/primitives/transaction-storage-proof/src/lib.rs

@@ -15,7 +15,7 @@
 // See the License for the specific language governing permissions and
 // limitations under the License.
 
-//! Storge proof primitives. Constains types and basic code to extract storage
+//! Storage proof primitives. Constains types and basic code to extract storage
 //! proofs for indexed transactions.
 
 #![cfg_attr(not(feature = "std"), no_std)]
@@ -49,6 +49,8 @@ impl IsFatalError for InherentError {
 	}
 }
 
+/// Holds a chunk of data retrieved from storage along with
+/// a proof that the data was stored at that location in the trie.
 #[derive(Encode, Decode, Clone, PartialEq, Debug)]
 pub struct TransactionStorageProof {
 	/// Data chunk that is proved to exist.
@@ -108,7 +110,7 @@ impl sp_inherents::InherentDataProvider for InherentDataProvider {
 	}
 }
 
-/// An utility function to extract chunk index from the source of randomness.
+/// A utility function to extract a chunk index from the source of randomness.
 pub fn random_chunk(random_hash: &[u8], total_chunks: u32) -> u32 {
 	let mut buf = [0u8; 8];
 	buf.copy_from_slice(&random_hash[0..8]);
@@ -116,18 +118,24 @@ pub fn random_chunk(random_hash: &[u8], total_chunks: u32) -> u32 {
 	(random_u64 % total_chunks as u64) as u32
 }
 
-/// An utility function to enocde transaction index as trie key.
+/// A utility function to encode transaction index as trie key.
 pub fn encode_index(input: u32) -> Vec<u8> {
 	codec::Encode::encode(&codec::Compact(input))
 }
 
 /// An interface to request indexed data from the client.
 pub trait IndexedBody<B: BlockT> {
+	/// Get all indexed transactions for a block,
+	/// including renewed transactions.
+	///
+	/// Note that this will only fetch transactions
+	/// that are indexed by the runtime with `storage_index_transaction`.
 	fn block_indexed_body(
 		&self,
 		number: NumberFor<B>,
 	) -> Result<Option<Vec<Vec<u8>>>, Error>;
 
+	/// Get block number for a block hash.
 	fn number(
 		&self,
 		hash: B::Hash,
@@ -237,4 +245,3 @@ pub mod registration {
 		).unwrap();
 	}
 }
-