f much better docs

Author: TheBlueMatt

lightning/src/routing/scoring.rs

@@ -796,8 +796,15 @@ impl<G: Deref<Target = NetworkGraph<L>>, L: Deref, T: Time> ProbabilisticScorerU
 	/// Query the historical estimated minimum and maximum liquidity available for sending a
 	/// payment over the channel with `scid` towards the given `target` node.
 	///
-	/// Returns the relative probabilities of the liquidity bounds being in each octile,
-	/// lower-bound first.
+	/// Returns two sets of 8 buckets. The first set describes the probability that the liquidity
+	/// lower-bound is in a given octile, the second describes the probability that the liquidity
+	/// upper-bound is in a given octile. Each bucket holds a `u16` representing the relative
+	/// probability of the bound being in the given octile.
+	///
+	/// For example, a value of `[0, 0, 0, 0, 0, 0, 32]` indicates that we belive the probability
+	/// of a bound being in the top octile to be 100%, and have never (recently) seen it in any
+	/// other octiles. A value of `[31, 0, 0, 0, 0, 0, 0, 32]` indicates we've seen the bound being
+	/// both in the top and bottom octile, and roughly with similar (recent) frequency.
 	pub fn historical_estimated_channel_liquidity_probabilities(&self, scid: u64, target: &NodeId)
 	-> Option<([u16; 8], [u16; 8])> {
 		let graph = self.network_graph.read_only();