Merge bitcoindevkit/bdk#686: doc: Document that list_transactions() might return unsorted txs

7fdacdbad40f4e9f6726b064d8eb4d93789e9990 doc: Document that list_transactions() might return unsorted txs, show how to sort them if needed (w0xlt)

Pull request description:

  This PR documents that `list_transactions()` might return unsorted transaction and shows how to sort them if needed.

  Closes #518.

ACKs for top commit:
  danielabrozzoni:
    re-ACK 7fdacdbad40f4e9f6726b064d8eb4d93789e9990

Tree-SHA512: 83bec98e1903d6dc6b8933e8994cb9d04aad059cee8a7b8e1e3a322cf52511364b36d0cd6be1c8cb1fd82c67f8be5a262bbd2c76e30b24eb4097c30f38aa8b10

src/wallet/mod.rs

@@ -438,11 +438,22 @@ where
         self.database.borrow().get_tx(txid, include_raw)
     }
 
-    /// Return the list of transactions made and received by the wallet
+    /// Return an unsorted list of transactions made and received by the wallet
     ///
     /// Optionally fill the [`TransactionDetails::transaction`] field with the raw transaction if
     /// `include_raw` is `true`.
     ///
+    /// To sort transactions, the following code can be used:
+    /// ```no_run
+    /// # let mut tx_list: Vec<bdk::TransactionDetails> = vec![];
+    /// tx_list.sort_by(|a, b| {
+    ///     b.confirmation_time
+    ///         .as_ref()
+    ///         .map(|t| t.height)
+    ///         .cmp(&a.confirmation_time.as_ref().map(|t| t.height))
+    /// });
+    /// ```
+    ///
     /// Note that this methods only operate on the internal database, which first needs to be
     /// [`Wallet::sync`] manually.
     pub fn list_transactions(&self, include_raw: bool) -> Result<Vec<TransactionDetails>, Error> {