Merge rust-bitcoin/rust-bitcoin#1709: Improve QR code formatting documentation

a6188a90c0 Improve QR code formatting documentation (Martin Habovstiak)

Pull request description:

  It wasn't obvious that displaying address with alternate formatting upper cases bech32 addresses.

  This change adds information about this and also a note about the compatibility of various wallets.

  BTW why do we prefix upper case `BITCOIN` only in case of bech32? Proper BIP21 should support it for all addresses. (And yest, it still does save space.)

ACKs for top commit:
  apoelstra:
    ACK a6188a90c0
  tcharding:
    ACK a6188a90c0

Tree-SHA512: b62b17664f12d4ce05296131cde9f307311b8114c457970f8e3f1beb4d6fd397981045c61c44e1da573623842b74b73d088f757f9ff063eb783ab69145102cd7

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",