From 0b5df8bb084cac748ddf8e427e8b404e2bb0b8a7 Mon Sep 17 00:00:00 2001 From: iximeow Date: Tue, 13 May 2025 13:02:12 -0700 Subject: [PATCH 1/2] add a workflow to check cargo doc and deny on docs issues at least, if i've plumbed the env var correctly. i am not an expert yaml programmer. --- .github/workflows/rust.yml | 11 +++++++++++ 1 file changed, 11 insertions(+) diff --git a/.github/workflows/rust.yml b/.github/workflows/rust.yml index 8ac74379c..6a2852aad 100644 --- a/.github/workflows/rust.yml +++ b/.github/workflows/rust.yml @@ -25,6 +25,17 @@ jobs: - name: Check style run: cargo fmt -- --check + check-docs: + runs-on: ubuntu-24.04 + steps: + - uses: actions/checkout@d632683dd7b4114ad314bca15554477dd762a938 + - name: Report cargo version + run: cargo --version + - name: Check docs + run: cargo doc --no-deps + env: + RUSTDOCFLAGS: -D warnings + clippy-lint: runs-on: ubuntu-24.04 steps: From d1c5a9e5d3988a517c2f301d5220ab28c454a169 Mon Sep 17 00:00:00 2001 From: iximeow Date: Tue, 13 May 2025 13:13:57 -0700 Subject: [PATCH 2/2] fix a few docs bugs and export HttpResponseContent HttpResponseError is made public at the crate root, but it requires implementers also implement HttpResponseContent. HttpResponseContent is *not* public, so implementations of HttpResponseError are constrained to only being types that are covered by blanket impls of HttpResponseContent. i personally don't need to do that, but it makes the docs funky and is probably an error. it's morally similar to a function returning a type which is not public. --- dropshot/src/error.rs | 4 ++-- dropshot/src/error_status_code.rs | 4 ++-- dropshot/src/lib.rs | 1 + dropshot/src/test_util.rs | 2 +- dropshot/tests/fail/bad_endpoint7.stderr | 12 ++++++------ dropshot/tests/fail/bad_trait_endpoint7.stderr | 16 ++++++++-------- 6 files changed, 20 insertions(+), 19 deletions(-) diff --git a/dropshot/src/error.rs b/dropshot/src/error.rs index 03ed3ab61..374da95b1 100644 --- a/dropshot/src/error.rs +++ b/dropshot/src/error.rs @@ -347,11 +347,11 @@ impl HttpError { /// If this error does not already have a header map (`self.header_map` is /// `None`), this method creates one. /// - /// Unlike [`HttpError::set_header`], this method takes `self` by value, + /// Unlike [`HttpError::add_header`], this method takes `self` by value, /// allowing it to be chained to form an expression that returns an /// `HttpError`. However, because this takes `self` by value, returning an /// error for an invalid header name or value will discard the `HttpError`. - /// To avoid this, use [`HttpError::set_header`] instead. + /// To avoid this, use [`HttpError::add_header`] instead. /// /// # Returns /// diff --git a/dropshot/src/error_status_code.rs b/dropshot/src/error_status_code.rs index 2d4784f0a..52b1b051f 100644 --- a/dropshot/src/error_status_code.rs +++ b/dropshot/src/error_status_code.rs @@ -16,7 +16,7 @@ use std::fmt; /// Alternatively, constants are provided for known error status codes, such as /// [`ErrorStatusCode::BAD_REQUEST`], [`ErrorStatusCode::NOT_FOUND`], /// [`ErrorStatusCode::INTERNAL_SERVER_ERROR`], and so on, including those in -/// the IANA HTTP Status Code Registry]( +/// the [IANA HTTP Status Code Registry]( /// https://www.iana.org/assignments/http-status-codes/http-status-codes.xhtml). /// Using these constants avoids the fallible conversion from an /// [`http::StatusCode`]. @@ -425,7 +425,7 @@ impl_status_code_wrapper! { /// /// Alternatively, constants are provided for known error status codes, such as /// [`ClientErrorStatusCode::BAD_REQUEST`], -/// [`ClientErrorStatusCode::NOT_FOUND`], including those in the IANA HTTP +/// [`ClientErrorStatusCode::NOT_FOUND`], including those in the [IANA HTTP /// Status Code Registry]( /// https://www.iana.org/assignments/http-status-codes/http-status-codes.xhtml). /// Using these constants avoids the fallible conversion from an diff --git a/dropshot/src/lib.rs b/dropshot/src/lib.rs index 52d380a27..bb62d7e98 100644 --- a/dropshot/src/lib.rs +++ b/dropshot/src/lib.rs @@ -909,6 +909,7 @@ pub use handler::FreeformBody; pub use handler::HttpCodedResponse; pub use handler::HttpResponse; pub use handler::HttpResponseAccepted; +pub use handler::HttpResponseContent; pub use handler::HttpResponseCreated; pub use handler::HttpResponseDeleted; pub use handler::HttpResponseError; diff --git a/dropshot/src/test_util.rs b/dropshot/src/test_util.rs index ddbfd7e9e..8b66f6870 100644 --- a/dropshot/src/test_util.rs +++ b/dropshot/src/test_util.rs @@ -243,7 +243,7 @@ impl ClientTestContext { } /// Temporarily configures the client to expect `E`-typed error responses, - /// rather than [`dropshot::HttpError`] error responses. + /// rather than [`dropshot::HttpError`][`crate::HttpError`] error responses. /// /// `ClientTestContext` expects that all error responses are /// `dropshot::HttpError`. For testing APIs that return other error types, this diff --git a/dropshot/tests/fail/bad_endpoint7.stderr b/dropshot/tests/fail/bad_endpoint7.stderr index 112744c51..2a0f3aa77 100644 --- a/dropshot/tests/fail/bad_endpoint7.stderr +++ b/dropshot/tests/fail/bad_endpoint7.stderr @@ -16,14 +16,14 @@ error[E0277]: the trait bound `Ret: serde::ser::Serialize` is not satisfied (T0, T1, T2, T3) (T0, T1, T2, T3, T4) and $N others - = note: required for `Ret` to implement `dropshot::handler::HttpResponseContent` + = note: required for `Ret` to implement `HttpResponseContent` note: required by a bound in `HttpResponseOk` --> src/handler.rs | | pub struct HttpResponseOk( | ^^^^^^^^^^^^^^^^^^^ required by this bound in `HttpResponseOk` -error[E0277]: the trait bound `Ret: dropshot::handler::HttpResponseContent` is not satisfied +error[E0277]: the trait bound `Ret: HttpResponseContent` is not satisfied --> tests/fail/bad_endpoint7.rs:25:23 | 25 | Ok(HttpResponseOk(Ret { @@ -45,7 +45,7 @@ error[E0277]: the trait bound `Ret: dropshot::handler::HttpResponseContent` is n (T0, T1, T2, T3) (T0, T1, T2, T3, T4) and $N others - = note: required for `Ret` to implement `dropshot::handler::HttpResponseContent` + = note: required for `Ret` to implement `HttpResponseContent` note: required by a bound in `HttpResponseOk` --> src/handler.rs | @@ -70,7 +70,7 @@ error[E0277]: the trait bound `Ret: serde::ser::Serialize` is not satisfied (T0, T1, T2, T3) (T0, T1, T2, T3, T4) and $N others - = note: required for `Ret` to implement `dropshot::handler::HttpResponseContent` + = note: required for `Ret` to implement `HttpResponseContent` note: required by a bound in `HttpResponseOk` --> src/handler.rs | @@ -98,7 +98,7 @@ error[E0277]: the trait bound `Ret: serde::ser::Serialize` is not satisfied (T0, T1, T2, T3) (T0, T1, T2, T3, T4) and $N others - = note: required for `Ret` to implement `dropshot::handler::HttpResponseContent` + = note: required for `Ret` to implement `HttpResponseContent` note: required by a bound in `HttpResponseOk` --> src/handler.rs | @@ -125,7 +125,7 @@ error[E0277]: the trait bound `Ret: serde::ser::Serialize` is not satisfied (T0, T1, T2, T3) (T0, T1, T2, T3, T4) and $N others - = note: required for `Ret` to implement `dropshot::handler::HttpResponseContent` + = note: required for `Ret` to implement `HttpResponseContent` note: required by a bound in `HttpResponseOk` --> src/handler.rs | diff --git a/dropshot/tests/fail/bad_trait_endpoint7.stderr b/dropshot/tests/fail/bad_trait_endpoint7.stderr index 799ab7ebf..8d12f140b 100644 --- a/dropshot/tests/fail/bad_trait_endpoint7.stderr +++ b/dropshot/tests/fail/bad_trait_endpoint7.stderr @@ -1,4 +1,4 @@ -error[E0277]: the trait bound `Ret: dropshot::handler::HttpResponseContent` is not satisfied +error[E0277]: the trait bound `Ret: HttpResponseContent` is not satisfied --> tests/fail/bad_trait_endpoint7.rs:41:27 | 41 | Ok(HttpResponseOk(Ret { x: "Oxide".to_string(), y: 0x1de })) @@ -16,7 +16,7 @@ error[E0277]: the trait bound `Ret: dropshot::handler::HttpResponseContent` is n (T0, T1, T2, T3) (T0, T1, T2, T3, T4) and $N others - = note: required for `Ret` to implement `dropshot::handler::HttpResponseContent` + = note: required for `Ret` to implement `HttpResponseContent` note: required by a bound in `dropshot::HttpResponseOk` --> src/handler.rs | @@ -41,7 +41,7 @@ error[E0277]: the trait bound `Ret: serde::ser::Serialize` is not satisfied (T0, T1, T2, T3) (T0, T1, T2, T3, T4) and $N others - = note: required for `Ret` to implement `dropshot::handler::HttpResponseContent` + = note: required for `Ret` to implement `HttpResponseContent` note: required by a bound in `dropshot::HttpResponseOk` --> src/handler.rs | @@ -66,7 +66,7 @@ error[E0277]: the trait bound `Ret: serde::ser::Serialize` is not satisfied (T0, T1, T2, T3) (T0, T1, T2, T3, T4) and $N others - = note: required for `Ret` to implement `dropshot::handler::HttpResponseContent` + = note: required for `Ret` to implement `HttpResponseContent` note: required by a bound in `dropshot::HttpResponseOk` --> src/handler.rs | @@ -93,14 +93,14 @@ error[E0277]: the trait bound `Ret: serde::ser::Serialize` is not satisfied (T0, T1, T2, T3) (T0, T1, T2, T3, T4) and $N others - = note: required for `Ret` to implement `dropshot::handler::HttpResponseContent` + = note: required for `Ret` to implement `HttpResponseContent` note: required by a bound in `dropshot::HttpResponseOk` --> src/handler.rs | | pub struct HttpResponseOk( | ^^^^^^^^^^^^^^^^^^^ required by this bound in `HttpResponseOk` -error[E0277]: the trait bound `Ret: dropshot::handler::HttpResponseContent` is not satisfied +error[E0277]: the trait bound `Ret: HttpResponseContent` is not satisfied --> tests/fail/bad_trait_endpoint7.rs:28:10 | 28 | ) -> Result, HttpError>; @@ -116,7 +116,7 @@ error[E0277]: the trait bound `Ret: dropshot::handler::HttpResponseContent` is n (T0, T1, T2, T3) (T0, T1, T2, T3, T4) and $N others - = note: required for `Ret` to implement `dropshot::handler::HttpResponseContent` + = note: required for `Ret` to implement `HttpResponseContent` note: required by a bound in `dropshot::HttpResponseOk` --> src/handler.rs | @@ -141,7 +141,7 @@ error[E0277]: the trait bound `Ret: serde::ser::Serialize` is not satisfied (T0, T1, T2, T3) (T0, T1, T2, T3, T4) and $N others - = note: required for `Ret` to implement `dropshot::handler::HttpResponseContent` + = note: required for `Ret` to implement `HttpResponseContent` note: required by a bound in `dropshot::HttpResponseOk` --> src/handler.rs |