contracts: Improve documentation of lazy deletion config (paritytech#…

…10582)

* Improve documentation of lazy deletion config

* Apply suggestions from code review

Co-authored-by: Sacha Lansky <[email protected]>

* Update frame/contracts/src/lib.rs

Co-authored-by: Andrew Jones <[email protected]>

* Improve wording

Co-authored-by: Sacha Lansky <[email protected]>
Co-authored-by: Andrew Jones <[email protected]>

frame/contracts/src/lib.rs

@@ -254,11 +254,30 @@ pub mod pallet {
 		/// In other words only the origin called "root contract" is allowed to execute then.
 		type CallStack: smallvec::Array<Item = Frame<Self>>;
 
-		/// The maximum number of tries that can be queued for deletion.
+		/// The maximum number of contracts that can be pending for deletion.
+		///
+		/// When a contract is deleted by calling `seal_terminate` it becomes inaccessible
+		/// immediately, but the deletion of the storage items it has accumulated is performed
+		/// later. The contract is put into the deletion queue. This defines how many
+		/// contracts can be queued up at the same time. If that limit is reached `seal_terminate`
+		/// will fail. The action must be retried in a later block in that case.
+		///
+		/// The reasons for limiting the queue depth are:
+		///
+		/// 1. The queue is in storage in order to be persistent between blocks. We want to limit
+		/// 	the amount of storage that can be consumed.
+		/// 2. The queue is stored in a vector and needs to be decoded as a whole when reading
+		///		it at the end of each block. Longer queues take more weight to decode and hence
+		///		limit the amount of items that can be deleted per block.
 		#[pallet::constant]
 		type DeletionQueueDepth: Get<u32>;
 
 		/// The maximum amount of weight that can be consumed per block for lazy trie removal.
+		///
+		/// The amount of weight that is dedicated per block to work on the deletion queue. Larger
+		/// values allow more trie keys to be deleted in each block but reduce the amount of
+		/// weight that is left for transactions. See [`Self::DeletionQueueDepth`] for more
+		/// information about the deletion queue.
 		#[pallet::constant]
 		type DeletionWeightLimit: Get<Weight>;
 
@@ -271,6 +290,7 @@ pub mod pallet {
 		type DepositPerByte: Get<BalanceOf<Self>>;
 
 		/// The amount of balance a caller has to pay for each storage item.
+		///
 		/// # Note
 		///
 		/// Changing this value for an existing chain might need a storage migration.