Tweak our_to_self_delay documentation wording to make it flow better

Author: TheBlueMatt

lightning/src/util/config.rs

@@ -23,18 +23,21 @@ pub struct ChannelHandshakeConfig {
 	///
 	/// Default value: 6.
 	pub minimum_depth: u32,
-	/// Set to the amount of time we require our counterparty to wait to claim their money.
+	/// Set to the number of blocks we require our counterparty to wait to claim their money (ie
+	/// the number of blocks we have to punish our counterparty if they broadcast a revoked
+	/// transaction).
 	///
-	/// It's one of the main parameter of our security model. We (or one of our watchtowers) MUST
-	/// be online to check for peer having broadcast a revoked transaction to steal our funds
-	/// at least once every our_to_self_delay blocks.
+	/// This is one of the main parameters of our security model. We (or one of our watchtowers) MUST
+	/// be online to check for revoked transactions on-chain at least once every our_to_self_delay
+	/// blocks (minus some margin to allow us enough time to broadcast and confirm a transaction,
+	/// possibly with time in between to RBF the spending transaction).
 	///
 	/// Meanwhile, asking for a too high delay, we bother peer to freeze funds for nothing in
 	/// case of an honest unilateral channel close, which implicitly decrease the economic value of
 	/// our channel.
 	///
-	/// Default value: [`BREAKDOWN_TIMEOUT`] (currently 144), we enforce it as a minimum at channel
-	/// opening so you can tweak config to ask for more security, not less.
+	/// Default value: [`BREAKDOWN_TIMEOUT`], we enforce it as a minimum at channel opening so you
+	/// can tweak config to ask for more security, not less.
 	pub our_to_self_delay: u16,
 	/// Set to the smallest value HTLC we will accept to process.
 	///