Merge rust-bitcoin#353: Improve types struct and enum rustdocs

9a4e53c Improve types struct and enum rustdocs (Jamil Lambert, PhD)

Pull request description:

  The rustdocs for the RPCs in types in inconsistent. In particular the sub structs and enums don't always mention which RPC they are part of. This makes it harder to understand which bit goes with which.

  Use the same language throughout so that when scanning through the code it is easier to follow.

  Make all the rustdocs consistent and mention which RPC they are part of.

ACKs for top commit:
  tcharding:
    ACK 9a4e53c

Tree-SHA512: 0f497179df047ff488e0edbfb9c2eb936c79e006d98285833d06ee988811fc8585e854880e6271e274d0d099e409986ebf272a618af96f7d41e2670876968afe

Author: tcharding

integration_test/tests/network.rs

@@ -81,7 +81,7 @@ fn network__get_network_info__modelled() {
     let model: Result<mtype::GetNetworkInfo, GetNetworkInfoError> = json.into_model();
     model.unwrap();
 
-    // Server version is returned as part of the getnetworkinfo method.
+    // Server version is part of the getnetworkinfo method.
     node.client.check_expected_server_version().expect("unexpected version");
 }
 

types/src/model/blockchain.rs

@@ -135,7 +135,7 @@ pub struct GetBlockchainInfo {
     pub warnings: Vec<String>,
 }
 
-/// Status of softfork.
+/// Softfork status. Part of `getblockchaininfo`.
 #[derive(Clone, Debug, PartialEq, Eq, Deserialize, Serialize)]
 #[serde(deny_unknown_fields)]
 pub struct Softfork {
@@ -150,7 +150,7 @@ pub struct Softfork {
     pub active: bool,
 }
 
-/// The softfork type: one of "buried", "bip9".
+/// The softfork type. Part of `getblockchaininfo`.
 #[derive(Copy, Clone, PartialEq, Eq, Debug, Deserialize, Serialize)]
 #[serde(rename_all = "lowercase")]
 pub enum SoftforkType {
@@ -164,7 +164,7 @@ pub enum SoftforkType {
     Bip9,
 }
 
-/// Status of BIP-9 softforks.
+/// BIP-9 softfork info. Part of `getblockchaininfo`.
 #[derive(Clone, PartialEq, Eq, Debug, Deserialize, Serialize)]
 #[serde(deny_unknown_fields)]
 pub struct Bip9SoftforkInfo {
@@ -184,7 +184,7 @@ pub struct Bip9SoftforkInfo {
     pub statistics: Option<Bip9SoftforkStatistics>,
 }
 
-/// BIP-9 softfork status: one of "defined", "started", "locked_in", "active", "failed".
+/// BIP-9 softfork status. Part of `getblockchaininfo`.
 #[derive(Copy, Clone, PartialEq, Eq, Debug, Deserialize, Serialize)]
 pub enum Bip9SoftforkStatus {
     /// BIP-9 softfork status "defined".
@@ -199,7 +199,7 @@ pub enum Bip9SoftforkStatus {
     Failed,
 }
 
-/// Statistics for a BIP-9 softfork.
+/// BIP-9 softfork statistics. Part of `getblockchaininfo`.
 #[derive(Clone, PartialEq, Eq, Debug, Deserialize, Serialize)]
 #[serde(deny_unknown_fields)]
 pub struct Bip9SoftforkStatistics {
@@ -356,7 +356,7 @@ pub struct GetChainStates {
     pub chain_states: Vec<ChainState>,
 }
 
-/// A single chainstate returned as part of `getchainstates`.
+/// A single chainstate. Part of `getchainstates`.
 #[derive(Clone, Debug, PartialEq, Deserialize, Serialize)]
 #[serde(deny_unknown_fields)]
 pub struct ChainState {
@@ -401,7 +401,7 @@ pub struct ChainTips {
     pub status: ChainTipsStatus,
 }
 
-/// The `status` field from an individual list item from the result of JSON-RPC method `getchaintips`.
+/// Chain tips status. Part of `getchaintips`.
 #[derive(Copy, Clone, PartialEq, Eq, Debug, Deserialize, Serialize)]
 #[serde(rename_all = "kebab-case")]
 pub enum ChainTipsStatus {
@@ -451,7 +451,7 @@ pub struct GetDeploymentInfo {
     pub deployments: std::collections::BTreeMap<String, DeploymentInfo>,
 }
 
-/// Deployment info. Returned as part of `getdeploymentinfo`.
+/// Deployment info. Part of `getdeploymentinfo`.
 #[derive(Clone, Debug, PartialEq, Deserialize, Serialize)]
 #[serde(deny_unknown_fields)]
 pub struct DeploymentInfo {
@@ -465,7 +465,7 @@ pub struct DeploymentInfo {
     pub bip9: Option<Bip9Info>,
 }
 
-/// Status of bip9 softforks. Returned as part of `getdeploymentinfo`.
+/// Status of bip9 softforks. Part of `getdeploymentinfo`.
 #[derive(Clone, Debug, PartialEq, Deserialize, Serialize)]
 #[serde(deny_unknown_fields)]
 pub struct Bip9Info {
@@ -489,7 +489,7 @@ pub struct Bip9Info {
     pub signalling: Option<String>,
 }
 
-/// Numeric statistics about signalling for a softfork. Returned as part of `getdeploymentinfo`.
+/// Numeric statistics about signalling for a softfork. Part of `getdeploymentinfo`.
 #[derive(Clone, Debug, PartialEq, Deserialize, Serialize)]
 #[serde(deny_unknown_fields)]
 pub struct Bip9Statistics {
@@ -535,7 +535,7 @@ pub struct GetMempoolDescendantsVerbose(pub BTreeMap<Txid, MempoolEntry>);
 #[serde(deny_unknown_fields)]
 pub struct GetMempoolEntry(pub MempoolEntry);
 
-/// A relative (ancestor or descendant) transaction of a transaction in the mempool.
+/// Mempool data. Part of `getmempoolentry`.
 #[derive(Clone, Debug, PartialEq, Deserialize, Serialize)]
 #[serde(deny_unknown_fields)]
 pub struct MempoolEntry {
@@ -565,7 +565,7 @@ pub struct MempoolEntry {
     pub ancestor_size: u32,
     /// Hash of serialized transaction, including witness data.
     pub wtxid: Wtxid,
-    /// (No docs in Core v0.17.)
+    /// (No docs in Core v0.17). Part of `getmempoolentry`.
     pub fees: MempoolEntryFees,
     /// Unconfirmed transactions used as inputs for this transaction (parent transaction id).
     pub depends: Vec<Txid>,
@@ -578,7 +578,7 @@ pub struct MempoolEntry {
     pub unbroadcast: Option<bool>,
 }
 
-/// (No docs in Core v0.17.)
+/// Fee object. Part of `getmempoolentry`.
 #[derive(Clone, Debug, PartialEq, Deserialize, Serialize)]
 #[serde(deny_unknown_fields)]
 pub struct MempoolEntryFees {
@@ -686,7 +686,7 @@ pub struct GetTxOutSetInfo {
 #[serde(deny_unknown_fields)]
 pub struct GetTxSpendingPrevout(pub Vec<GetTxSpendingPrevoutItem>);
 
-/// An individual result item from `gettxspendingprevout`.
+/// A transaction item. Part of `gettxspendingprevout`.
 #[derive(Clone, Debug, PartialEq, Eq, Deserialize, Serialize)]
 #[serde(deny_unknown_fields)]
 pub struct GetTxSpendingPrevoutItem {
@@ -709,7 +709,7 @@ pub struct GetDescriptorActivity {
     pub activity: Vec<ActivityEntry>,
 }
 
-/// Enum representing either a spend or receive activity entry using model types.
+/// A spend or receive activity entry. Part of `getdescriptoractivity`.
 #[derive(Clone, Debug, PartialEq, Deserialize, Serialize)]
 pub enum ActivityEntry {
     /// The spend activity using `model::SpendActivity`.
@@ -718,7 +718,7 @@ pub enum ActivityEntry {
     Receive(ReceiveActivity),
 }
 
-/// Models a 'spend' activity event with strongly typed fields.
+/// Models a 'spend' activity event. Part of `getdescriptoractivity`.
 #[derive(Clone, Debug, PartialEq, Deserialize, Serialize)]
 #[serde(deny_unknown_fields)]
 pub struct SpendActivity {
@@ -740,7 +740,7 @@ pub struct SpendActivity {
     pub prevout_spk: ScriptPubkey,
 }
 
-/// Models a 'receive' activity event with strongly typed fields.
+/// Models a 'receive' activity event. Part of `getdescriptoractivity`
 #[derive(Clone, Debug, PartialEq, Deserialize, Serialize)]
 #[serde(deny_unknown_fields)]
 pub struct ReceiveActivity {
@@ -772,7 +772,7 @@ pub struct LoadTxOutSet {
     pub path: String,
 }
 
-/// Models the result of the JSON-RPC method `scanblocks` start.
+/// Models the result of the JSON-RPC method `scanblocks` whan `action = start`.
 #[derive(Clone, Debug, PartialEq, Deserialize, Serialize)]
 pub struct ScanBlocksStart {
     /// The height we started the scan from

types/src/model/mining.rs

@@ -70,9 +70,7 @@ pub struct GetBlockTemplate {
     pub default_witness_commitment: Option<String>,
 }
 
-/// Contents of non-coinbase transactions that should be included in the next block.
-///
-/// Returned as part of `getblocktemplate`.
+/// Non-coinbase transaction contents. Part of `getblocktemplate`.
 #[derive(Clone, Debug, PartialEq, Deserialize, Serialize)]
 #[serde(deny_unknown_fields)]
 pub struct BlockTemplateTransaction {
@@ -132,7 +130,7 @@ pub struct GetMiningInfo {
     pub warnings: Vec<String>,
 }
 
-/// Represents the `next` block information within the GetMiningInfo result.
+/// Represents the `next` block information. Part of `getmininginfo`.
 #[derive(Clone, Debug, PartialEq, Deserialize, Serialize)]
 #[serde(deny_unknown_fields)]
 pub struct NextBlockInfo {
@@ -151,6 +149,7 @@ pub struct NextBlockInfo {
 #[serde(deny_unknown_fields)]
 pub struct GetPrioritisedTransactions(pub BTreeMap<Txid, PrioritisedTransaction>);
 
+/// An individual prioritised transaction. Part of `getprioritisedtransactions`.
 #[derive(Clone, Debug, PartialEq, Deserialize, Serialize)]
 #[serde(deny_unknown_fields)]
 pub struct PrioritisedTransaction {

types/src/model/network.rs

@@ -46,7 +46,7 @@ pub struct GetNetworkInfo {
     pub warnings: Vec<String>,
 }
 
-/// Part of the result of the JSON-RPC method `getnetworkinfo` (information per network).
+/// Information per network. Part of `getnetworkinfo`.
 #[derive(Clone, Debug, PartialEq, Deserialize, Serialize)]
 #[serde(deny_unknown_fields)]
 pub struct GetNetworkInfoNetwork {
@@ -62,7 +62,7 @@ pub struct GetNetworkInfoNetwork {
     pub proxy_randomize_credentials: bool,
 }
 
-/// Part of the result of the JSON-RPC method `getnetworkinfo` (local address info).
+/// Local address info. Part of `getnetworkinfo`.
 #[derive(Clone, Debug, PartialEq, Eq, Deserialize, Serialize)]
 #[serde(deny_unknown_fields)]
 pub struct GetNetworkInfoAddress {

types/src/model/raw_transactions.rs

@@ -30,7 +30,7 @@ pub struct AnalyzePsbt {
     pub next: String,
 }
 
-/// Represents an input in a PSBT operation.
+/// An input in a PSBT operation. Part of `analyzepsbt`.
 #[derive(Clone, Debug, PartialEq, Deserialize, Serialize)]
 #[serde(deny_unknown_fields)]
 pub struct AnalyzePsbtInput {
@@ -44,7 +44,7 @@ pub struct AnalyzePsbtInput {
     pub next: Option<String>,
 }
 
-/// Represents missing elements required to complete an input.
+/// Missing elements required to complete an input. Part of `analyzepsbt`.
 #[derive(Clone, Debug, PartialEq, Deserialize, Serialize)]
 #[serde(deny_unknown_fields)]
 pub struct AnalyzePsbtInputMissing {
@@ -202,7 +202,7 @@ pub struct SignRawTransaction {
     pub errors: Vec<SignFail>,
 }
 
-/// Represents a script verification error.
+/// A script verification error. Part of `signrawtransaction`.
 #[derive(Clone, Debug, PartialEq, Deserialize, Serialize)]
 #[serde(deny_unknown_fields)]
 pub struct SignFail {
@@ -272,7 +272,7 @@ pub struct TestMempoolAccept {
     pub results: Vec<MempoolAcceptance>,
 }
 
-/// Models a single mempool acceptance test result. Returned as part of `testmempoolaccept`.
+/// Models a single mempool acceptance test result. Part of `testmempoolaccept`.
 #[derive(Clone, Debug, PartialEq, Deserialize, Serialize)]
 #[serde(deny_unknown_fields)]
 pub struct MempoolAcceptance {
@@ -292,7 +292,7 @@ pub struct MempoolAcceptance {
     pub reject_details: Option<String>,
 }
 
-/// Models the fees field. Returned as part of `testmempoolaccept`.
+/// Models the fees field. Part of `testmempoolaccept`.
 #[derive(Clone, Debug, PartialEq, Deserialize, Serialize)]
 #[serde(deny_unknown_fields)]
 pub struct MempoolAcceptanceFees {