diff --git a/bitcoin/src/address.rs b/bitcoin/src/address.rs
index a7bb0b31..9ed55d16 100644
--- a/bitcoin/src/address.rs
+++ b/bitcoin/src/address.rs
@@ -575,6 +575,7 @@ pub struct AddressEncoding<'a> {
     pub bech32_hrp: &'a str,
 }
 
+/// Formats bech32 as upper case if alternate formatting is chosen (`{:#}`).
 impl<'a> fmt::Display for AddressEncoding<'a> {
     fn fmt(&self, fmt: &mut fmt::Formatter) -> fmt::Result {
         match self.payload {
@@ -937,6 +938,26 @@ impl Address {
     ///
     /// Quoting BIP 173 "inside QR codes uppercase SHOULD be used, as those permit the use of
     /// alphanumeric mode, which is 45% more compact than the normal byte mode."
+    ///
+    /// Note however that despite BIP21 explicitly stating that the `bitcoin:` prefix should be
+    /// parsed as case-insensitive many wallets got this wrong and don't parse correctly.
+    /// [See compatibility table.](https://github.com/btcpayserver/btcpayserver/issues/2110)
+    ///
+    /// If you want to avoid allocation you can use alternate display instead:
+    /// ```
+    /// # use core::fmt::Write;
+    /// # const ADDRESS: &str = "BC1QW508D6QEJXTDG4Y5R3ZARVARY0C5XW7KV8F3T4";
+    /// # let address = ADDRESS.parse::<bitcoin::Address<_>>().unwrap().assume_checked();
+    /// # let mut writer = String::new();
+    /// # // magic trick to make error handling look better
+    /// # (|| -> Result<(), core::fmt::Error> {
+    ///
+    /// write!(writer, "{:#}", address)?;
+    ///
+    /// # Ok(())
+    /// # })().unwrap();
+    /// # assert_eq!(writer, ADDRESS);
+    /// ```
     pub fn to_qr_uri(&self) -> String {
         let schema = match self.payload {
             Payload::WitnessProgram { .. } => "BITCOIN",