f docs

Author: TheBlueMatt

lightning/src/routing/scoring.rs

@@ -323,10 +323,11 @@ type ConfiguredTime = Eternity;
 /// *Optimally Reliable & Cheap Payment Flows on the Lightning Network* by Rene Pickhardt
 /// and Stefan Richter [[1]] (i.e. `(upper_bound - payment_amount) / (upper_bound - lower_bound)`).
 ///
-/// This probability is converted into a linear score and multiplied with the
-/// [`liquidity_penalty_multiplier_msat`] and [`liquidity_penalty_amount_multiplier_msat`]
-/// parameters to calculate a concrete penalty in milli-satoshis. See the documentation of those
-/// parameters for the exact formulas.
+/// This probability is combined with the [`liquidity_penalty_multiplier_msat`] and
+/// [`liquidity_penalty_amount_multiplier_msat`] parameters to calculate a concrete penalty in
+/// milli-satoshis. The penalties, when added across all hops, have the property of being linear in
+/// terms of the entire path's success probability. This allows the router to directly compare
+/// penalties for different paths. See the documentation of those parameters for the exact formulas.
 ///
 /// The liquidity bounds are decayed by halving them every [`liquidity_offset_half_life`].
 ///