[docs] Docs and doctests succeed for all features (#369)

`cargo test --doc` and `cargo doc` now succeed on all feature
combinations.

Previously, we had a separate CI job step for running doc tests, and we
had doc tests disabled by default in `Cargo.toml`. Now, we can get rid
of the separate CI job, and we can get rid of the disablement in
`Cargo.toml`.

Author: joshlf

.github/workflows/ci.yml

@@ -179,20 +179,6 @@ jobs:
       # wasm32-wasi once those work.
       if: matrix.toolchain == 'nightly' && matrix.target != 'riscv64gc-unknown-linux-gnu' && matrix.target != 'wasm32-wasi'
 
-    - name: Run doc tests
-      # We explicitly pass `--doc` here because doc tests are disabled by
-      # default in zerocopy's `Cargo.toml`. This is because some doc examples
-      # make use of derives, and so would fail without the `derive` feature
-      # enabled. We skip this step for `zerocopy` when the `derive` feature is
-      # omitted for that reason.
-      run: ./cargo.sh +${{ matrix.toolchain }} test --doc --package ${{ matrix.crate }} --target ${{ matrix.target }} ${{ matrix.features }} --verbose
-      # Only run tests when targetting x86 (32- or 64-bit) - we're executing on
-      # x86_64, so we can't run tests for any non-x86 target.
-      #
-      # TODO(https://github.com/dtolnay/trybuild/issues/184#issuecomment-1269097742):
-      # Run compile tests when building for other targets.
-      if: ${{ (contains(matrix.target, 'x86_64') || contains(matrix.target, 'i686')) && !(matrix.crate == 'zerocopy' && !contains(matrix.features, 'derive')) }}
-
     - name: Clippy check
       run: ./cargo.sh +${{ matrix.toolchain }} clippy --package ${{ matrix.crate }} --target ${{ matrix.target }} ${{ matrix.features }} --tests --verbose
       # Clippy improves the accuracy of lints over time, and fixes bugs. Only
@@ -210,12 +196,11 @@ jobs:
       run: |
         export RUSTDOCFLAGS="${{ matrix.toolchain == 'nightly' && '-Z unstable-options --document-hidden-items' || '' }} $RUSTDOCFLAGS"
         ./cargo.sh +${{ matrix.toolchain }} doc --document-private-items --package ${{ matrix.crate }} ${{ matrix.features }}
-      # When the `alloc` feature is disabled, `cargo doc` fails because we link
-      # to `alloc::vec::Vec` in a doc comment, and the `alloc` crate is not in
-      # scope without the `alloc` feature. This isn't a big deal because we care
-      # primarily about `cargo doc` working for `docs.rs`, which enables the
-      # `alloc` feature.
-      if: matrix.features != '' && matrix.features != '--no-default-features'
+      # When the `byteorder` feature is disabled, `cargo doc` fails because we
+      # link to the `byteorder` module in doc comments. This isn't a big deal
+      # because we primarily care about `cargo doc` working for `docs.rs`, which
+      # enables the `byteorder` feature.
+      if: matrix.features != '--no-default-features'
 
     # Check semver compatibility with the most recently-published version on
     # crates.io. We do this in the matrix rather than in its own job so that it

Cargo.toml

@@ -28,20 +28,6 @@ all-features = true
 pinned-stable = "1.69.0"
 pinned-nightly = "nightly-2023-05-25"
 
-# Don't run doctests during `cargo test` without the `--doc` flag (the `--doc`
-# flag will still cause doctests to run despite this directive). Running
-# doctests without the `derive` feature fails because our doc examples make use
-# of zerocopy-derive, which is an optional dependency and is disabled by
-# default. Unfortunately, there's no way to automatically include
-# zerocopy-derive as a dependency during doctests, so we have to do it manually
-# by passing the appropriate flags in CI.
-[lib]
-doctest = false
-# Not technically necessary - this is the default value for `path` - but if a
-# `lib` section is present, then `cargo readme` expects it to have a `path`
-# field, and will fail if it's missing.
-path = "src/lib.rs"
-
 [features]
 default = ["byteorder"]
 

src/byteorder.rs

@@ -29,7 +29,8 @@
 //! One use of these types is for representing network packet formats, such as
 //! UDP:
 //!
-//! ```edition2021
+//! ```rust,edition2021
+//! # #[cfg(feature = "derive")] { // This example uses derives, and won't compile without them
 //! use zerocopy::{AsBytes, ByteSlice, FromBytes, FromZeroes, Ref, Unaligned};
 //! use zerocopy::byteorder::network_endian::U16;
 //!
@@ -59,6 +60,7 @@
 //!
 //!     // more getters...
 //! }
+//! # }
 //! ```
 
 use core::{

src/lib.rs

@@ -1381,6 +1381,7 @@ macro_rules! transmute {
 /// simply a reference to that type.
 ///
 /// ```rust
+/// # #[cfg(feature = "derive")] { // This example uses derives, and won't compile without them
 /// use zerocopy::{AsBytes, ByteSlice, ByteSliceMut, FromBytes, FromZeroes, Ref, Unaligned};
 ///
 /// #[derive(FromZeroes, FromBytes, AsBytes, Unaligned)]
@@ -1413,6 +1414,7 @@ macro_rules! transmute {
 ///         self.header.src_port = src_port;
 ///     }
 /// }
+/// # }
 /// ```
 pub struct Ref<B, T: ?Sized>(B, PhantomData<T>);
 
@@ -2404,8 +2406,16 @@ mod sealed {
 /// method would involve reallocation, and `split_at` must be a very cheap
 /// operation in order for the utilities in this crate to perform as designed.
 ///
-/// [`Vec<u8>`]: alloc::vec::Vec
 /// [`split_at`]: crate::ByteSlice::split_at
+// It may seem overkill to go to this length to ensure that this doc link never
+// breaks. We do this because it simplifies CI - it means that generating docs
+// always succeeds, so we don't need special logic to only generate docs under
+// certain features.
+#[cfg_attr(feature = "alloc", doc = "[`Vec<u8>`]: alloc::vec::Vec")]
+#[cfg_attr(
+    not(feature = "alloc"),
+    doc = "[`Vec<u8>`]: https://doc.rust-lang.org/std/vec/struct.Vec.html"
+)]
 pub unsafe trait ByteSlice:
     Deref<Target = [u8]> + Sized + self::sealed::ByteSliceSealed
 {