- * Private routing paths between a public node and the target may be included in `last_hops`.
- * Currently, only the last hop in each path is considered.
+ * Private routing paths between a public node and the target may be included in `params.payee`.
+ *
+ * If some channels aren't announced, it may be useful to fill in `first_hops` with the results
+ * from [`ChannelManager::list_usable_channels`]. If it is filled in, the view of our local
+ * channels from [`NetworkGraph`] will be ignored, and only those in `first_hops` will be used.
+ *
+ * The fees on channels from us to the next hop are ignored as they are assumed to all be equal.
+ * However, the enabled/disabled bit on such channels as well as the `htlc_minimum_msat` /
+ * `htlc_maximum_msat` *are* checked as they may change based on the receiving node.
+ *
+ * # Note
+ *
+ * May be used to re-compute a [`Route`] when handling a [`Event::PaymentPathFailed`]. Any
+ * adjustments to the [`NetworkGraph`] and channel scores should be made prior to calling this
+ * function.