session, staking: add comments about sorted vecs

frame/session/src/lib.rs

@@ -413,7 +413,9 @@ decl_storage! {
 
 		/// Indices of disabled validators.
 		///
-		/// The set is cleared when `on_session_ending` returns a new set of identities.
+		/// The vec is always kept sorted so that we can find whether a given validator is
+		/// disabled using binary search. It gets cleared when `on_session_ending` returns
+		/// a new set of identities.
 		DisabledValidators get(fn disabled_validators): Vec<u32>;
 
 		/// The next session keys for a validator.

frame/staking/src/pallet/mod.rs

@@ -439,9 +439,11 @@ pub mod pallet {
 	/// disabled.
 	///
 	/// This value should be a superset of disabled validators since not all offences lead to the
-	/// validator being disabled (if there was no slash). This is needed to track the percentage
-	/// of validators that have offended in the current era, ensuring a new era is forced if
-	/// `OffendingValidatorsThreshold` is reached. The set is cleared when the era ends.
+	/// validator being disabled (if there was no slash). This is needed to track the percentage of
+	/// validators that have offended in the current era, ensuring a new era is forced if
+	/// `OffendingValidatorsThreshold` is reached. The vec is always kept sorted so that we can find
+	/// whether a given validator has previously offended using binary search. It gets cleared when
+	/// the era ends.
 	#[pallet::storage]
 	#[pallet::getter(fn offending_validators)]
 	pub type OffendingValidators<T: Config> = StorageValue<_, Vec<(u32, bool)>, ValueQuery>;