Clean up feature/module documentation with docs.rs features (#518)

run with `RUSTDOCFLAGS="--cfg docsrs" cargo doc --all-features --open`

- match `send` module feature gating to `receive` module gating. I like
this because it makes what's available explicit, and hides stuff you
don't want in the default configuration, but I could understand removing
if it seems like excessive complexity in cfging (API changing)
- Put explicit feature labels on optional modules with `cfg_attr` (this
needs the RUSTDOCFLAGS)
- Remove public feature-specific content-type consts. They're
encapsulated in the state machine now. (API changing)
- remove obsolete base64 re-export since our state machine covers it.
(API changing)
- Add module docs to public modules without fuss 
- Get rid of feature switching in doc strings.

Discovered these flaws with docs in while addressing #504.

payjoin-cli/Cargo.toml

@@ -37,7 +37,7 @@ hyper = { version = "1", features = ["http1", "server"], optional = true }
 hyper-rustls = { version = "0.26", optional = true }
 hyper-util = { version = "0.1", optional = true }
 log = "0.4.7"
-payjoin = { version = "0.22.0", features = ["base64"], default-features = false }
+payjoin = { version = "0.22.0", default-features = false }
 rcgen = { version = "0.11.1", optional = true }
 reqwest = { version = "0.12", default-features = false }
 rustls = { version = "0.22.4", optional = true }

payjoin/Cargo.toml

@@ -17,7 +17,6 @@ exclude = ["tests"]
 
 [features]
 default = ["v2"]
-base64 = ["bitcoin/base64"]
 #[doc = "Core features for payjoin state machines"]
 _core = ["bitcoin/rand", "serde_json", "url", "bitcoin_uri"]
 directory = []
@@ -49,4 +48,5 @@ tokio = { version = "1.12.0", features = ["full"] }
 tracing = "0.1.40"
 
 [package.metadata.docs.rs]
-features = ["base64", "v2", "io"]
+all-features = true
+rustdoc-args = ["--cfg", "docsrs"]

payjoin/src/directory.rs

@@ -1,3 +1,5 @@
+//! Types relevant to the Payjoin Directory as defined in BIP 77.
+
 pub const ENCAPSULATED_MESSAGE_BYTES: usize = 8192;
 
 /// A 64-bit identifier used to identify Payjoin Directory entries.

payjoin/src/io.rs

@@ -1,3 +1,5 @@
+//! IO-related types and functions. Specifically, fetching OHTTP keys from a payjoin directory.
+
 use reqwest::{Client, Proxy};
 
 use crate::{OhttpKeys, Url};

payjoin/src/lib.rs

@@ -1,3 +1,5 @@
+#![cfg_attr(docsrs, feature(doc_cfg))]
+
 //! # Payjoin implementation in Rust
 //!
 //! Supercharge payment batching to save you fees and preserve your privacy.
@@ -34,9 +36,11 @@ pub use crate::ohttp::OhttpKeys;
 #[cfg(any(feature = "v2", feature = "directory"))]
 pub(crate) mod bech32;
 #[cfg(feature = "directory")]
+#[cfg_attr(docsrs, doc(cfg(feature = "directory")))]
 pub mod directory;
 
 #[cfg(feature = "io")]
+#[cfg_attr(docsrs, doc(cfg(feature = "io")))]
 pub mod io;
 #[cfg(feature = "_core")]
 pub(crate) mod psbt;
@@ -47,8 +51,6 @@ pub use request::*;
 #[cfg(feature = "_core")]
 mod uri;
 
-#[cfg(feature = "base64")]
-pub use bitcoin::base64;
 #[cfg(feature = "_core")]
 pub use uri::{PjParseError, PjUri, Uri, UriExt};
 #[cfg(feature = "_core")]

payjoin/src/receive/mod.rs

@@ -1,3 +1,14 @@
+//! Receive Payjoin
+//!
+//! This module contains types and methods used to implement receiving via Payjoin.
+//!
+//! For most use cases, we recommended enabling the `v2` feature, as it is
+//! backwards compatible and provides the most convenient experience for users and implementors.
+//! To use version 2, refer to `receive::v2` module documentation.
+//!
+//! If you specifically need to use
+//! version 1, refer to the `receive::v1` module documentation after enabling the `v1` feature.
+
 use bitcoin::{psbt, AddressType, TxIn, TxOut};
 pub(crate) use error::InternalPayloadError;
 pub use error::{Error, JsonError, OutputSubstitutionError, PayloadError, SelectionError};
@@ -9,11 +20,13 @@ mod error;
 pub(crate) mod optional_parameters;
 
 #[cfg(feature = "v1")]
+#[cfg_attr(docsrs, doc(cfg(feature = "v1")))]
 pub mod v1;
 #[cfg(not(feature = "v1"))]
 pub(crate) mod v1;
 
 #[cfg(feature = "v2")]
+#[cfg_attr(docsrs, doc(cfg(feature = "v2")))]
 pub mod v2;
 
 /// Helper to construct a pair of (txin, psbtin) with some built-in validation

payjoin/src/receive/v1/mod.rs

@@ -1,4 +1,4 @@
-//! Receive Payjoin v1
+//! Receive BIP 78 Payjoin v1
 //!
 //! This module contains types and methods used to receive payjoin via BIP78.
 //! Usage is pretty simple:

payjoin/src/receive/v2/mod.rs

@@ -1,3 +1,4 @@
+//! Receive BIP 77 Payjoin v2
 use std::str::FromStr;
 use std::time::{Duration, SystemTime};
 

payjoin/src/request.rs

@@ -1,9 +1,9 @@
 use url::Url;
 
-pub const V1_REQ_CONTENT_TYPE: &str = "text/plain";
+const V1_REQ_CONTENT_TYPE: &str = "text/plain";
 
 #[cfg(feature = "v2")]
-pub const V2_REQ_CONTENT_TYPE: &str = "message/ohttp-req";
+const V2_REQ_CONTENT_TYPE: &str = "message/ohttp-req";
 
 /// Represents data that needs to be transmitted to the receiver or payjoin directory.
 /// Ensure the `Content-Length` is set to the length of `body`. (most libraries do this automatically)

payjoin/src/send/mod.rs

@@ -4,10 +4,10 @@
 //!
 //! For most use cases, we recommended enabling the `v2` feature, as it is
 //! backwards compatible and provides the most convenient experience for users and implementors.
-#![cfg_attr(feature = "v2", doc = "To use version 2, refer to [`v2`] module documentation.")]
+//! To use version 2, refer to `send::v2` module documentation.
 //!
 //! If you specifically need to use
-//! version 1, refer to the [`v1`] module documentation.
+//! version 1, refer to the `send::v1` module documentation after enabling the `v1` feature.
 
 use std::str::FromStr;
 
@@ -24,8 +24,15 @@ use crate::psbt::PsbtExt;
 compile_error!("This crate currently only supports 32 bit and 64 bit architectures");
 
 mod error;
+
+#[cfg(feature = "v1")]
+#[cfg_attr(docsrs, doc(cfg(feature = "v1")))]
 pub mod v1;
+#[cfg(not(feature = "v1"))]
+pub(crate) mod v1;
+
 #[cfg(feature = "v2")]
+#[cfg_attr(docsrs, doc(cfg(feature = "v2")))]
 pub mod v2;
 
 type InternalResult<T> = Result<T, InternalProposalError>;

payjoin/src/send/v1.rs

@@ -1,4 +1,4 @@
-//! Send Payjoin
+//! Send BIP 78 Payjoin v1
 //!
 //! This module contains types and methods used to implement sending via [BIP78
 //! Payjoin](https://github.com/bitcoin/bips/blob/master/bip-0078.mediawiki).

payjoin/src/send/v2/mod.rs

@@ -1,4 +1,4 @@
-//! Send Payjoin
+//! Send BIP 77 Payjoin v2
 //!
 //! This module contains types and methods used to implement sending via [BIP77
 //! Payjoin](https://github.com/bitcoin/bips/pull/1483).