Tweak our_to_self_delay documentation wording to make it flow better

diff --git a/lightning/src/util/config.rs b/lightning/src/util/config.rs
index a288caf460b943e3f45de1ee8a41bfd7161df442..4a9f300638a4c4c3b2ad7d243b58c2f569557841 100644 (file)
--- a/lightning/src/util/config.rs
+++ b/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.
        ///