From 822c99222d6eb26c2da2e99fbea4bc21bd81fa6c Mon Sep 17 00:00:00 2001
From: Tobin Harding <me@tobin.cc>
Date: Fri, 19 Nov 2021 09:37:34 +1100
Subject: [PATCH] Improve constructor rustdocs for Address

Improve the rustdocs for the various `Address` constructors by putting
the brief description on a separate line with further description in its
own paragraph. This is the layout best practice for function documentation
using rustdocs.

Also, favour 'creates' over 'constructs' because it is more common in
the docs of this struct.
---
 src/util/address.rs | 26 ++++++++++++++++----------
 1 file changed, 16 insertions(+), 10 deletions(-)

diff --git a/src/util/address.rs b/src/util/address.rs
index 52b2d302..a8ed1633 100644
--- a/src/util/address.rs
+++ b/src/util/address.rs
@@ -418,8 +418,9 @@ pub struct Address {
 serde_string_impl!(Address, "a Bitcoin address");
 
 impl Address {
-    /// Constructs a pay to (compressed) public key hash address from a public key. This is the
-    /// preferred non-witness type address.
+    /// Creates a pay to (compressed) public key hash address from a public key.
+    ///
+    /// This is the preferred non-witness type address.
     #[inline]
     pub fn p2pkh(pk: &ecdsa::PublicKey, network: Network) -> Address {
         let mut hash_engine = PubkeyHash::engine();
@@ -431,8 +432,10 @@ impl Address {
         }
     }
 
-    /// Creates a pay to script hash P2SH address from a script. This address type was introduced
-    /// with BIP16 and is the popular type to implement multi-sig these days.
+    /// Creates a pay to script hash P2SH address from a script.
+    ///
+    /// This address type was introduced with BIP16 and is the popular type to implement multi-sig
+    /// these days.
     #[inline]
     pub fn p2sh(script: &script::Script, network: Network) -> Result<Address, Error> {
         if script.len() > MAX_SCRIPT_ELEMENT_SIZE{
@@ -444,8 +447,9 @@ impl Address {
         })
     }
 
-    /// Creates a witness pay to public key address from a public key. This is the native segwit
-    /// address type for an output redeemable with a single signature.
+    /// Creates a witness pay to public key address from a public key.
+    ///
+    /// This is the native segwit address type for an output redeemable with a single signature.
     ///
     /// # Errors
     /// Will only return an error if an uncompressed public key is provided.
@@ -466,8 +470,9 @@ impl Address {
         })
     }
 
-    /// Creates a pay to script address that embeds a witness pay to public key. This is a segwit
-    /// address type that looks familiar (as p2sh) to legacy clients.
+    /// Creates a pay to script address that embeds a witness pay to public key.
+    ///
+    /// This is a segwit address type that looks familiar (as p2sh) to legacy clients.
     ///
     /// # Errors
     /// Will only return an Error if an uncompressed public key is provided.
@@ -500,8 +505,9 @@ impl Address {
         }
     }
 
-    /// Creates a pay to script address that embeds a witness pay to script hash address. This is a
-    /// segwit address type that looks familiar (as p2sh) to legacy clients.
+    /// Creates a pay to script address that embeds a witness pay to script hash address.
+    ///
+    /// This is a segwit address type that looks familiar (as p2sh) to legacy clients.
     pub fn p2shwsh(script: &script::Script, network: Network) -> Address {
         let ws = script::Builder::new()
             .push_int(0)