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
This commit is contained in:
Tobin C. Harding 2022-04-19 15:26:26 +10:00
parent 33a50831ce
commit 9896f27eae
2 changed files with 18 additions and 20 deletions

View File

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

View File

@ -47,7 +47,7 @@ pub struct SighashCache<T: Deref<Target=Transaction>> {
/// Common cache for taproot and segwit inputs, `None` for legacy inputs. /// Common cache for taproot and segwit inputs, `None` for legacy inputs.
common_cache: Option<CommonCache>, 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>, segwit_cache: Option<SegwitCache>,
/// Cache for taproot v1 inputs. /// Cache for taproot v1 inputs.
@ -104,8 +104,8 @@ pub struct ScriptPath<'s> {
leaf_version: LeafVersion, leaf_version: LeafVersion,
} }
/// Hashtype of an input's signature, encoded in the last byte of the signature. Fixed values so /// Hashtype of an input's signature, encoded in the last byte of the signature.
/// they can be cast as integer types for encoding. /// Fixed values so they can be cast as integer types for encoding.
#[derive(Copy, Clone, PartialEq, Eq, PartialOrd, Ord, Hash, Debug)] #[derive(Copy, Clone, PartialEq, Eq, PartialOrd, Ord, Hash, Debug)]
pub enum SchnorrSighashType { pub enum SchnorrSighashType {
/// 0x0: Used when not explicitly specified, defaults to [`SchnorrSighashType::All`] /// 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 /// 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>>( pub fn taproot_encode_signing_data_to<Write: io::Write, T: Borrow<TxOut>>(
&mut self, &mut self,
mut writer: Write, mut writer: Write,