Lint docs (payjoin#426)

Author: DanGould

.github/ISSUE_TEMPLATE/minor-release.md

@@ -56,8 +56,8 @@ Tag and publish new release:
   - In the body of the tag message put a copy of the **Summary** and **Changelog** for the release.
   - Make sure the tag is signed, for extra safety use the explicit `--sign` flag.
 - [ ] Wait for the CI to finish one last time.
-- [ ] Push the new tag to the `payjoin/rust-payjoin` repo.
 - [ ] Build the docs locally to ensure they are building correctly.
+- [ ] Push the new tag to the `payjoin/rust-payjoin` repo.
 - [ ] Publish the crate in question crates to crates.io.
 - [ ] Create the release on GitHub.
   - Go to "tags", click on the dots on the right and select "Create Release".

.github/workflows/rust.yml

@@ -49,8 +49,10 @@ jobs:
         uses: Swatinem/rust-cache@v2
       - name: "Install clippy"
         run: rustup component add clippy --toolchain nightly-x86_64-unknown-linux-gnu
-      - name: "Run linting"
+      - name: "Run code linting"
         run: bash contrib/lint.sh
+      - name: "Run documentation linting"
+        run: RUSTDOCFLAGS="-D warnings" cargo doc --no-deps --all-features --document-private-items
 
   Coverage:
     name: Code coverage

payjoin/src/receive/mod.rs

@@ -518,7 +518,7 @@ impl WantsInputs {
     /// UIH1 and UIH2 according to the BlockSci practice
     /// BlockSci UIH1 and UIH2:
     /// if min(in) > min(out) then UIH1 else UIH2
-    /// https://eprint.iacr.org/2022/589.pdf
+    /// <https://eprint.iacr.org/2022/589.pdf>
     fn avoid_uih(
         &self,
         candidate_inputs: impl IntoIterator<Item = InputPair>,

payjoin/src/receive/v2/mod.rs

@@ -216,7 +216,7 @@ impl Receiver {
 /// The sender's original PSBT and optional parameters
 ///
 /// This type is used to process the request. It is returned by
-/// [`UncheckedProposal::from_request()`](super::::UncheckedProposal::from_request()).
+/// [`Receiver::process_res()`].
 ///
 /// If you are implementing an interactive payment processor, you should get extract the original
 /// transaction with extract_tx_to_schedule_broadcast() and schedule, followed by checking
@@ -393,7 +393,7 @@ impl WantsInputs {
     /// UIH1 and UIH2 according to the BlockSci practice
     /// BlockSci UIH1 and UIH2:
     /// if min(in) > min(out) then UIH1 else UIH2
-    /// https://eprint.iacr.org/2022/589.pdf
+    /// <https://eprint.iacr.org/2022/589.pdf>
     pub fn try_preserving_privacy(
         &self,
         candidate_inputs: impl IntoIterator<Item = InputPair>,

payjoin/src/send/mod.rs

@@ -10,7 +10,7 @@
 //! 3. (optional) Spawn a thread or async task that will broadcast the original PSBT fallback after
 //!    delay (e.g. 1 minute) unless canceled
 //! 4. Construct the [`Sender`] using [`SenderBuilder`] with the PSBT and payjoin uri
-//! 5. Send the request(s) and receive response(s) by following on the extracted [`Context`]
+//! 5. Send the request(s) and receive response(s) by following on the extracted Context
 //! 6. Sign and finalize the Payjoin Proposal PSBT
 //! 7. Broadcast the Payjoin Transaction (and cancel the optional fallback broadcast)
 //!
@@ -70,8 +70,8 @@ impl<'a> SenderBuilder<'a> {
     /// Prepare an HTTP request and request context to process the response
     ///
     /// An HTTP client will own the Request data while Context sticks around so
-    /// a `(Request, Context)` tuple is returned from `RequestBuilder::build()`
-    /// to keep them separated.
+    /// a `(Request, Context)` tuple is returned from [`SenderBuilder::build_recommended()`]
+    /// (or other `build` methods) to keep them separated.
     pub fn from_psbt_and_uri(psbt: Psbt, uri: PjUri<'a>) -> Result<Self, CreateRequestError> {
         Ok(Self {
             psbt,
@@ -339,6 +339,10 @@ impl Sender {
     pub fn endpoint(&self) -> &Url { &self.endpoint }
 }
 
+/// Data required to validate the response.
+///
+/// This type is used to process the response. Get it from [`Sender`]'s build methods.
+/// Then call [`Self::process_response`] on it to continue BIP78 flow.
 #[derive(Debug, Clone)]
 pub struct V1Context {
     psbt_context: PsbtContext,
@@ -451,10 +455,7 @@ impl V2GetContext {
     }
 }
 
-/// Data required for validation of response.
-///
-/// This type is used to process the response. Get it from [`RequestBuilder`]'s build methods.
-/// Then you only need to call [`Self::process_response`] on it to continue BIP78 flow.
+/// Data required to validate the response against the original PSBT.
 #[derive(Debug, Clone)]
 pub struct PsbtContext {
     original_psbt: Psbt,