Add rustdoc tests to CI (#1210)

There's a few rustdoc tests in the code base however CI did not
previously ensure they passed or even compiled. This change fixes broken
doctests and adds a new job to run these in CI.

This will allow us to write new doctests and be sure that they will be
validated by CI. For example, we may wish to write doctests asserting
safety justifications.

### Does this change impact existing behavior?

CI change only.

### Does this change need a changelog entry?

No, this changes CI only.

---

By submitting this pull request, I confirm that my contribution is made
under the terms of the Apache 2.0 license and I agree to the terms of
the [Developer Certificate of Origin
(DCO)](https://developercertificate.org/).

Signed-off-by: Daniel Carl Jones <[email protected]>

.github/workflows/tests.yml

@@ -266,6 +266,39 @@ jobs:
       - name: Build CRT binding documentation
         run: cargo doc --no-deps -p mountpoint-s3-crt
 
+  doctests:
+    name: rustdoc tests
+    runs-on: ubuntu-latest
+
+    steps:
+      - name: Checkout code
+        uses: actions/checkout@v4
+        with:
+          submodules: true
+      - name: Set up Rust toolchain
+        uses: actions-rust-lang/setup-rust-toolchain@v1
+        with:
+          # setup-rust-toolchain sets "-D warnings" by default, and Rust treats any warning as compile error.
+          # We need to this currently because `vendor/fuser` contains some warnings and it breaks the build.
+          rustflags: ""
+      - name: Install operating system dependencies
+        uses: ./.github/actions/install-dependencies
+        with:
+          fuseVersion: 2
+      - name: Cargo cache
+        uses: actions/cache@v3
+        with:
+          path: |
+            ~/.cargo/bin/
+            ~/.cargo/registry/index/
+            ~/.cargo/registry/cache/
+            ~/.cargo/git/db/
+            target/
+          key: ${{ runner.os }}-${{ runner.arch }}-${{ github.job }}-cargo-${{ hashFiles('**/Cargo.lock') }}
+      - name: Run doctests for all crates
+        # Some of the generated bindings seem to be interpretted as rustdoc tests, skip them for now.
+        run: cargo test --doc -- --skip=generated::aws_hash_table_foreach
+
   deny:
     name: Licenses
     runs-on: ubuntu-latest

mountpoint-s3-client/src/lib.rs

@@ -16,12 +16,13 @@
 //! To construct a new S3 client and download an object from a bucket in the `us-east-1` region:
 //! ```no_run
 //! # async fn test() {
-//! use futures::TryStreamExt;
+//! use futures::{TryFutureExt, TryStreamExt};
+//! use mountpoint_s3_client::types::GetObjectParams;
 //! use mountpoint_s3_client::{S3CrtClient, ObjectClient};
 //!
 //! let client = S3CrtClient::new(Default::default()).expect("client construction failed");
 //!
-//! let response = client.get_object("my-bucket", "my-key", &GetObjectParams::new().await.expect("get_object failed"));
+//! let response = client.get_object("my-bucket", "my-key", &GetObjectParams::new()).await.expect("get_object failed");
 //! let body = response.map_ok(|(offset, body)| body.to_vec()).try_concat().await.expect("body streaming failed");
 //! # }
 //! ```
@@ -33,8 +34,7 @@
 //!
 //! let config = S3ClientConfig::new()
 //!                 .endpoint_config(EndpointConfig::new("us-west-2"))
-//!                 .auth_config(S3ClientAuthConfig::NoSigning)
-//!                 .user_agent_prefix("my-test-client");
+//!                 .auth_config(S3ClientAuthConfig::NoSigning);
 //! let client = S3CrtClient::new(config).expect("client construction failed");
 //! ```
 //!