add a workflow to deny on docs issues + fix docs issues

.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:

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
     ///

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

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;

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

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<T: HttpResponseContent + Send + Sync + 'static>(
    |                              ^^^^^^^^^^^^^^^^^^^ 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
    |

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<T: HttpResponseContent + Send + Sync + 'static>(
    |                              ^^^^^^^^^^^^^^^^^^^ 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<HttpResponseOk<Ret>, 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
    |