psbt: Improve documentation

Improve documentation in `psbt/mod.rs` by doing:

- Use full sentences (full stops and capitalisation)
- Use 100 line column width
- Use back ticks and links as appropriate
- Use `Errors` section
- Use third person tense to describe functions

Author: tcharding

src/util/psbt/mod.rs

@@ -53,13 +53,12 @@ pub type Psbt = PartiallySignedTransaction;
 #[derive(Debug, Clone, PartialEq, Eq)]
 #[cfg_attr(feature = "serde", derive(Serialize, Deserialize))]
 pub struct PartiallySignedTransaction {
-    /// The unsigned transaction, scriptSigs and witnesses for each input must be
-    /// empty.
+    /// The unsigned transaction, scriptSigs and witnesses for each input must be empty.
     pub unsigned_tx: Transaction,
     /// The version number of this PSBT. If omitted, the version number is 0.
     pub version: u32,
     /// A global map from extended public keys to the used key fingerprint and
-    /// derivation path as defined by BIP 32
+    /// derivation path as defined by BIP 32.
     pub xpub: BTreeMap<ExtendedPubKey, KeySource>,
     /// Global proprietary key-value pairs.
     #[cfg_attr(feature = "serde", serde(with = "crate::serde_utils::btreemap_as_seq_byte_values"))]
@@ -68,11 +67,9 @@ pub struct PartiallySignedTransaction {
     #[cfg_attr(feature = "serde", serde(with = "crate::serde_utils::btreemap_as_seq_byte_values"))]
     pub unknown: BTreeMap<raw::Key, Vec<u8>>,
 
-    /// The corresponding key-value map for each input in the unsigned
-    /// transaction.
+    /// The corresponding key-value map for each input in the unsigned transaction.
     pub inputs: Vec<Input>,
-    /// The corresponding key-value map for each output in the unsigned
-    /// transaction.
+    /// The corresponding key-value map for each output in the unsigned transaction.
     pub outputs: Vec<Output>,
 }
 
@@ -103,8 +100,7 @@ impl PartiallySignedTransaction {
         })
     }
 
-    /// Checks that unsigned transaction does not have scriptSig's or witness
-    /// data
+    /// Checks that unsigned transaction does not have scriptSig's or witness data.
     fn unsigned_tx_checks(&self) -> Result<(), Error> {
         for txin in &self.unsigned_tx.input {
             if !txin.script_sig.is_empty() {
@@ -119,8 +115,11 @@ impl PartiallySignedTransaction {
         Ok(())
     }
 
-    /// Create a PartiallySignedTransaction from an unsigned transaction, error
-    /// if not unsigned
+    /// Creates a PSBT from an unsigned transaction.
+    ///
+    /// # Errors
+    ///
+    /// If transactions is not unsigned.
     pub fn from_unsigned_tx(tx: Transaction) -> Result<Self, Error> {
         let psbt = PartiallySignedTransaction {
             inputs: vec![Default::default(); tx.input.len()],
@@ -136,8 +135,7 @@ impl PartiallySignedTransaction {
         Ok(psbt)
     }
 
-    /// Extract the Transaction from a PartiallySignedTransaction by filling in
-    /// the available signature information in place.
+    /// Extracts the `Transaction` from a PSBT by filling in the available signature information.
     pub fn extract_tx(self) -> Transaction {
         let mut tx: Transaction = self.unsigned_tx;
 
@@ -222,13 +220,13 @@ mod display_from_str {
     use crate::consensus::encode::{Error, self};
     use base64::display::Base64Display;
 
-    /// Error happening during PSBT decoding from Base64 string
+    /// Error encountered during PSBT decoding from Base64 string.
     #[derive(Debug)]
     #[cfg_attr(docsrs, doc(cfg(feature = "base64")))]
     pub enum PsbtParseError {
-        /// Error in internal PSBT data structure
+        /// Error in internal PSBT data structure.
         PsbtEncoding(Error),
-        /// Error in PSBT Base64 encoding
+        /// Error in PSBT Base64 encoding.
         Base64Encoding(::base64::DecodeError)
     }
 

src/util/sighash.rs

@@ -47,7 +47,7 @@ pub struct SighashCache<T: Deref<Target=Transaction>> {
     /// Common cache for taproot and segwit inputs, `None` for legacy inputs.
     common_cache: Option<CommonCache>,
 
-    /// Cache for segwit v0 inputs.
+    /// Cache for segwit v0 inputs (the result of another round of sha256 on `common_cache`).
     segwit_cache: Option<SegwitCache>,
 
     /// Cache for taproot v1 inputs.
@@ -104,8 +104,8 @@ pub struct ScriptPath<'s> {
     leaf_version: LeafVersion,
 }
 
-/// Hashtype of an input's signature, encoded in the last byte of the signature. Fixed values so
-/// they can be cast as integer types for encoding.
+/// Hashtype of an input's signature, encoded in the last byte of the signature.
+/// Fixed values so they can be cast as integer types for encoding.
 #[derive(Copy, Clone, PartialEq, Eq, PartialOrd, Ord, Hash, Debug)]
 pub enum SchnorrSighashType {
     /// 0x0: Used when not explicitly specified, defaults to [`SchnorrSighashType::All`]
@@ -349,7 +349,7 @@ impl<R: Deref<Target = Transaction>> SighashCache<R> {
     }
 
     /// Encodes the BIP341 signing data for any flag type into a given object implementing a
-    /// `io::Write` trait.
+    /// [`io::Write`] trait.
     pub fn taproot_encode_signing_data_to<Write: io::Write, T: Borrow<TxOut>>(
         &mut self,
         mut writer: Write,