Merge rust-bitcoin/rust-bitcoin#753: Put rustdocs above attributes

533120899e Put rustdocs above attributes (Tobin Harding)

Pull request description:

  (Trivial / Very low priority PR)

  Rust idiomatic style is to put the rustdoc _above_ any attributes on types, functions, etc.

  Audit the codebase and move comments/attributes to the correct place. Add a trailing full stop at times to neaten things up a little extra.

  Done after discussion [here](https://github.com/rust-bitcoin/rust-secp256k1/pull/353#discussion_r778393138)

ACKs for top commit:
  Kixunil:
    ACK 533120899e
  RCasatta:
    ACK 533120899e

Tree-SHA512: 7cd00dc46de813cbe3f96417bb4b13980064e10110b421224496c8b64bbe87b61b6c757cc621fde1d05754be6ecdc08acdb51fd8978e3f820d2d93f7104062d1

src/blockdata/script.rs

@@ -42,8 +42,8 @@ use policy::DUST_RELAY_TX_FEE;
 use util::ecdsa::PublicKey;
 use util::address::WitnessVersion;
 
+/// A Bitcoin script.
 #[derive(Clone, Default, PartialOrd, Ord, PartialEq, Eq, Hash)]
-/// A Bitcoin script
 pub struct Script(Box<[u8]>);
 
 impl AsRef<[u8]> for Script {
@@ -101,8 +101,8 @@ impl ::core::str::FromStr for Script {
     }
 }
 
+/// An object which can be used to construct a script piece by piece.
 #[derive(PartialEq, Eq, Debug, Clone)]
-/// An object which can be used to construct a script piece by piece
 pub struct Builder(Vec<u8>, Option<opcodes::All>);
 display_from_debug!(Builder);
 
@@ -118,17 +118,17 @@ pub enum Error {
     EarlyEndOfScript,
     /// Tried to read an array off the stack as a number when it was more than 4 bytes
     NumericOverflow,
-    #[cfg(feature = "bitcoinconsensus")]
-    #[cfg_attr(docsrs, doc(cfg(feature = "bitcoinconsensus")))]
     /// Error validating the script with bitcoinconsensus library
+    #[cfg(feature = "bitcoinconsensus")]
+    #[cfg_attr(docsrs, doc(cfg(feature = "bitcoinconsensus")))]
     BitcoinConsensus(bitcoinconsensus::Error),
-    #[cfg(feature = "bitcoinconsensus")]
-    #[cfg_attr(docsrs, doc(cfg(feature = "bitcoinconsensus")))]
     /// Can not find the spent output
-    UnknownSpentOutput(OutPoint),
     #[cfg(feature = "bitcoinconsensus")]
     #[cfg_attr(docsrs, doc(cfg(feature = "bitcoinconsensus")))]
+    UnknownSpentOutput(OutPoint),
     /// Can not serialize the spending transaction
+    #[cfg(feature = "bitcoinconsensus")]
+    #[cfg_attr(docsrs, doc(cfg(feature = "bitcoinconsensus")))]
     SerializationError
 }
 
@@ -496,21 +496,21 @@ impl Script {
         }
     }
 
+    /// Shorthand for [Self::verify_with_flags] with flag [bitcoinconsensus::VERIFY_ALL]
     #[cfg(feature="bitcoinconsensus")]
     #[cfg_attr(docsrs, doc(cfg(feature = "bitcoinconsensus")))]
-    /// Shorthand for [Self::verify_with_flags] with flag [bitcoinconsensus::VERIFY_ALL]
     pub fn verify (&self, index: usize, amount: ::Amount, spending: &[u8]) -> Result<(), Error> {
         self.verify_with_flags(index, amount, spending, ::bitcoinconsensus::VERIFY_ALL)
     }
 
-    #[cfg(feature="bitcoinconsensus")]
-    #[cfg_attr(docsrs, doc(cfg(feature = "bitcoinconsensus")))]
     /// Verify spend of an input script
     /// # Parameters
     ///  * `index` - the input index in spending which is spending this transaction
     ///  * `amount` - the amount this script guards
     ///  * `spending` - the transaction that attempts to spend the output holding this script
     ///  * `flags` - verification flags, see [bitcoinconsensus::VERIFY_ALL] and similar
+    #[cfg(feature="bitcoinconsensus")]
+    #[cfg_attr(docsrs, doc(cfg(feature = "bitcoinconsensus")))]
     pub fn verify_with_flags<F: Into<u32>>(&self, index: usize, amount: ::Amount, spending: &[u8], flags: F) -> Result<(), Error> {
         Ok(bitcoinconsensus::verify_with_flags (&self.0[..], amount.as_sat(), spending, index, flags.into())?)
     }

src/blockdata/transaction.rs

@@ -506,18 +506,18 @@ impl Transaction {
         }
     }
 
+    /// Shorthand for [Self::verify_with_flags] with flag [bitcoinconsensus::VERIFY_ALL]
     #[cfg(feature="bitcoinconsensus")]
     #[cfg_attr(docsrs, doc(cfg(feature = "bitcoinconsensus")))]
-    /// Shorthand for [Self::verify_with_flags] with flag [bitcoinconsensus::VERIFY_ALL]
     pub fn verify<S>(&self, spent: S) -> Result<(), script::Error>
         where S: FnMut(&OutPoint) -> Option<TxOut> {
         self.verify_with_flags(spent, ::bitcoinconsensus::VERIFY_ALL)
     }
 
-    #[cfg(feature="bitcoinconsensus")]
-    #[cfg_attr(docsrs, doc(cfg(feature = "bitcoinconsensus")))]
     /// Verify that this transaction is able to spend its inputs
     /// The lambda spent should not return the same TxOut twice!
+    #[cfg(feature="bitcoinconsensus")]
+    #[cfg_attr(docsrs, doc(cfg(feature = "bitcoinconsensus")))]
     pub fn verify_with_flags<S, F>(&self, mut spent: S, flags: F) -> Result<(), script::Error>
         where S: FnMut(&OutPoint) -> Option<TxOut>, F : Into<u32> {
         let tx = encode::serialize(&*self);

src/consensus/params.rs

@@ -50,8 +50,8 @@ const MAX_BITS_REGTEST: Uint256 = Uint256([
     0x7fffff0000000000u64,
 ]);
 
-#[derive(Debug, Clone)]
 /// Parameters that influence chain consensus.
+#[derive(Debug, Clone)]
 pub struct Params {
     /// Network for which parameters are valid.
     pub network: Network,

src/internal_macros.rs

@@ -49,38 +49,38 @@ macro_rules! impl_consensus_encoding {
 macro_rules! impl_array_newtype {
     ($thing:ident, $ty:ty, $len:expr) => {
         impl $thing {
-            #[inline]
             /// Converts the object to a raw pointer
+            #[inline]
             pub fn as_ptr(&self) -> *const $ty {
                 let &$thing(ref dat) = self;
                 dat.as_ptr()
             }
 
-            #[inline]
             /// Converts the object to a mutable raw pointer
+            #[inline]
             pub fn as_mut_ptr(&mut self) -> *mut $ty {
                 let &mut $thing(ref mut dat) = self;
                 dat.as_mut_ptr()
             }
 
-            #[inline]
             /// Returns the length of the object as an array
+            #[inline]
             pub fn len(&self) -> usize { $len }
 
-            #[inline]
             /// Returns whether the object, as an array, is empty. Always false.
+            #[inline]
             pub fn is_empty(&self) -> bool { false }
 
-            #[inline]
             /// Returns the underlying bytes.
+            #[inline]
             pub fn as_bytes(&self) -> &[$ty; $len] { &self.0 }
 
-            #[inline]
             /// Returns the underlying bytes.
+            #[inline]
             pub fn to_bytes(&self) -> [$ty; $len] { self.0.clone() }
 
-            #[inline]
             /// Returns the underlying bytes.
+            #[inline]
             pub fn into_bytes(self) -> [$ty; $len] { self.0 }
         }
 

src/network/message.rs

@@ -118,8 +118,8 @@ impl fmt::Display for CommandStringError {
 #[cfg(feature = "std")]
 impl ::std::error::Error for CommandStringError { }
 
-#[derive(Clone, Debug, PartialEq, Eq)]
 /// A Network message
+#[derive(Clone, Debug, PartialEq, Eq)]
 pub struct RawNetworkMessage {
     /// Magic bytes to identify the network these messages are meant for
     pub magic: u32,

src/network/message_filter.rs

@@ -5,8 +5,8 @@
 
 use hash_types::{BlockHash, FilterHash, FilterHeader};
 
-#[derive(PartialEq, Eq, Clone, Debug)]
 /// getcfilters message
+#[derive(PartialEq, Eq, Clone, Debug)]
 pub struct GetCFilters {
     /// Filter type for which headers are requested
     pub filter_type: u8,
@@ -17,8 +17,8 @@ pub struct GetCFilters {
 }
 impl_consensus_encoding!(GetCFilters, filter_type, start_height, stop_hash);
 
-#[derive(PartialEq, Eq, Clone, Debug)]
 /// cfilter message
+#[derive(PartialEq, Eq, Clone, Debug)]
 pub struct CFilter {
     /// Byte identifying the type of filter being returned
     pub filter_type: u8,
@@ -29,8 +29,8 @@ pub struct CFilter {
 }
 impl_consensus_encoding!(CFilter, filter_type, block_hash, filter);
 
-#[derive(PartialEq, Eq, Clone, Debug)]
 /// getcfheaders message
+#[derive(PartialEq, Eq, Clone, Debug)]
 pub struct GetCFHeaders {
     /// Byte identifying the type of filter being returned
     pub filter_type: u8,
@@ -41,8 +41,8 @@ pub struct GetCFHeaders {
 }
 impl_consensus_encoding!(GetCFHeaders, filter_type, start_height, stop_hash);
 
-#[derive(PartialEq, Eq, Clone, Debug)]
 /// cfheaders message
+#[derive(PartialEq, Eq, Clone, Debug)]
 pub struct CFHeaders {
     /// Filter type for which headers are requested
     pub filter_type: u8,
@@ -55,8 +55,8 @@ pub struct CFHeaders {
 }
 impl_consensus_encoding!(CFHeaders, filter_type, stop_hash, previous_filter_header, filter_hashes);
 
-#[derive(PartialEq, Eq, Clone, Debug)]
 /// getcfcheckpt message
+#[derive(PartialEq, Eq, Clone, Debug)]
 pub struct GetCFCheckpt {
     /// Filter type for which headers are requested
     pub filter_type: u8,
@@ -65,8 +65,8 @@ pub struct GetCFCheckpt {
 }
 impl_consensus_encoding!(GetCFCheckpt, filter_type, stop_hash);
 
-#[derive(PartialEq, Eq, Clone, Debug)]
 /// cfcheckpt message
+#[derive(PartialEq, Eq, Clone, Debug)]
 pub struct CFCheckpt {
     /// Filter type for which headers are requested
     pub filter_type: u8,

src/util/address.rs

@@ -528,8 +528,8 @@ impl<'a> fmt::Display for AddressEncoding<'a> {
     }
 }
 
-#[derive(Clone, PartialEq, Eq, PartialOrd, Ord, Hash)]
 /// A Bitcoin address.
+#[derive(Clone, PartialEq, Eq, PartialOrd, Ord, Hash)]
 pub struct Address {
     /// The type of the address.
     pub payload: Payload,

src/util/ecdsa.rs

@@ -171,8 +171,8 @@ impl FromStr for PublicKey {
     }
 }
 
-#[derive(Copy, Clone, PartialEq, Eq)]
 /// A Bitcoin ECDSA private key
+#[derive(Copy, Clone, PartialEq, Eq)]
 pub struct PrivateKey {
     /// Whether this private key should be serialized as compressed
     pub compressed: bool,

src/util/misc.rs

@@ -175,17 +175,17 @@ mod message_signing {
             })
         }
 
+        /// Convert a signature from base64 encoding.
         #[cfg(feature = "base64")]
         #[cfg_attr(docsrs, doc(cfg(feature = "base64")))]
-        /// Convert a signature from base64 encoding.
         pub fn from_base64(s: &str) -> Result<MessageSignature, MessageSignatureError> {
             let bytes = ::base64::decode(s).map_err(|_| MessageSignatureError::InvalidBase64)?;
             MessageSignature::from_slice(&bytes)
         }
 
+        /// Convert to base64 encoding.
         #[cfg(feature = "base64")]
         #[cfg_attr(docsrs, doc(cfg(feature = "base64")))]
-        /// Convert to base64 encoding.
         pub fn to_base64(&self) -> String {
             ::base64::encode(&self.serialize()[..])
         }

src/util/psbt/error.rs

@@ -23,8 +23,8 @@ use util::psbt::raw;
 use hashes;
 use util::bip32::ExtendedPubKey;
 
+/// Enum for marking psbt hash error.
 #[derive(Copy, Clone, PartialEq, Eq, PartialOrd, Ord, Hash, Debug)]
-/// Enum for marking psbt hash error
 pub enum PsbtHash {
     Ripemd,
     Sha256,

src/util/sighash.rs

@@ -718,8 +718,8 @@ impl From<io::Error> for Error {
     }
 }
 
+/// The `Annex` struct is a slice wrapper enforcing first byte to be `0x50`.
 #[derive(Clone, PartialEq, Eq, Hash, Debug)]
-/// The `Annex` struct is a slice wrapper enforcing first byte to be `0x50`
 pub struct Annex<'a>(&'a [u8]);
 
 impl<'a> Annex<'a> {

src/util/uint.rs

@@ -505,9 +505,8 @@ macro_rules! construct_uint {
 construct_uint!(Uint256, 4);
 construct_uint!(Uint128, 2);
 
-/// Invalid slice length
+/// Invalid slice length.
 #[derive(Debug, PartialEq, Eq, PartialOrd, Ord, Clone, Copy, Hash)]
-/// Invalid slice length
 pub struct ParseLengthError {
     /// The length of the slice de-facto
     pub actual: usize,