run doc test in parallel (#387)

.cargo/config.toml

@@ -1,3 +1,5 @@
 [alias]
 chk = "check --workspace --all-features --tests --examples --bins"
 lint = "clippy --workspace --all-features --tests --examples --bins -- -Dclippy::todo"
+ci-test = "test --workspace --all-features --lib --tests --no-fail-fast -- --nocapture"
+ci-doctest = "test --workspace --all-features --doc --no-fail-fast -- --nocapture"

.github/workflows/ci.yml

@@ -104,9 +104,7 @@ jobs:
       - name: tests
         if: matrix.target.triple != 'x86_64-pc-windows-gnu'
         uses: actions-rs/cargo@v1
-        with:
+        with: { command: ci-test }
-          command: test
-          args: --workspace --all-features --no-fail-fast -- --nocapture
 
       - name: Generate coverage file
         if: >
@@ -129,3 +127,34 @@ jobs:
         run: |
           cargo install cargo-cache --version 0.6.2 --no-default-features --features ci-autoclean
           cargo-cache
+
+  rustdoc:
+    name: rustdoc
+    runs-on: ubuntu-latest
+
+    steps:
+      - uses: actions/checkout@v2
+
+      - name: Install Rust (nightly)
+        uses: actions-rs/toolchain@v1
+        with:
+          toolchain: nightly-x86_64-unknown-linux-gnu
+          profile: minimal
+          override: true
+
+      - name: Generate Cargo.lock
+        uses: actions-rs/cargo@v1
+        with: { command: generate-lockfile }
+      - name: Cache Dependencies
+        uses: Swatinem/rust-cache@v1.3.0
+
+      - name: Install cargo-hack
+        uses: actions-rs/cargo@v1
+        with:
+          command: install
+          args: cargo-hack
+
+      - name: doc tests
+        uses: actions-rs/cargo@v1
+        timeout-minutes: 40
+        with: { command: ci-doctest }

actix-codec/src/framed.rs

@@ -21,14 +21,13 @@ bitflags::bitflags! {
 }
 
 pin_project_lite::pin_project! {
-    /// A unified `Stream` and `Sink` interface to an underlying I/O object, using
+    /// A unified `Stream` and `Sink` interface to an underlying I/O object, using the `Encoder` and
-    /// the `Encoder` and `Decoder` traits to encode and decode frames.
+    /// `Decoder` traits to encode and decode frames.
     ///
-    /// Raw I/O objects work with byte sequences, but higher-level code usually
+    /// Raw I/O objects work with byte sequences, but higher-level code usually wants to batch these
-    /// wants to batch these into meaningful chunks, called "frames". This
+    /// into meaningful chunks, called "frames". This method layers framing on top of an I/O object,
-    /// method layers framing on top of an I/O object, by using the `Encoder`/`Decoder`
+    /// by using the `Encoder`/`Decoder` traits to handle encoding and decoding of message frames.
-    /// traits to handle encoding and decoding of message frames. Note that
+    /// Note that the incoming and outgoing frame types may be distinct.
-    /// the incoming and outgoing frame types may be distinct.
     pub struct Framed<T, U> {
         #[pin]
         io: T,
@@ -44,10 +43,9 @@ where
     T: AsyncRead + AsyncWrite,
     U: Decoder,
 {
-    /// This function returns a *single* object that is both `Stream` and
+    /// This function returns a *single* object that is both `Stream` and `Sink`; grouping this into
-    /// `Sink`; grouping this into a single object is often useful for layering
+    /// a single object is often useful for layering things like gzip or TLS, which require both
-    /// things like gzip or TLS, which require both read and write access to the
+    /// read and write access to the underlying object.
-    /// underlying object.
     pub fn new(io: T, codec: U) -> Framed<T, U> {
         Framed {
             io,
@@ -70,21 +68,18 @@ impl<T, U> Framed<T, U> {
         &mut self.codec
     }
 
-    /// Returns a reference to the underlying I/O stream wrapped by
+    /// Returns a reference to the underlying I/O stream wrapped by `Frame`.
-    /// `Frame`.
     ///
-    /// Note that care should be taken to not tamper with the underlying stream
+    /// Note that care should be taken to not tamper with the underlying stream of data coming in as
-    /// of data coming in as it may corrupt the stream of frames otherwise
+    /// it may corrupt the stream of frames otherwise being worked with.
-    /// being worked with.
     pub fn io_ref(&self) -> &T {
         &self.io
     }
 
     /// Returns a mutable reference to the underlying I/O stream.
     ///
-    /// Note that care should be taken to not tamper with the underlying stream
+    /// Note that care should be taken to not tamper with the underlying stream of data coming in as
-    /// of data coming in as it may corrupt the stream of frames otherwise
+    /// it may corrupt the stream of frames otherwise being worked with.
-    /// being worked with.
     pub fn io_mut(&mut self) -> &mut T {
         &mut self.io
     }
@@ -184,10 +179,9 @@ impl<T, U> Framed<T, U> {
     {
         loop {
             let mut this = self.as_mut().project();
-            // Repeatedly call `decode` or `decode_eof` as long as it is
+            // Repeatedly call `decode` or `decode_eof` as long as it is "readable". Readable is
-            // "readable". Readable is defined as not having returned `None`. If
+            // defined as not having returned `None`. If the upstream has returned EOF, and the
-            // the upstream has returned EOF, and the decoder is no longer
+            // decoder is no longer readable, it can be assumed that the decoder will never become
-            // readable, it can be assumed that the decoder will never become
             // readable again, at which point the stream is terminated.
 
             if this.flags.contains(Flags::READABLE) {
@@ -215,7 +209,7 @@ impl<T, U> Framed<T, U> {
 
             debug_assert!(!this.flags.contains(Flags::EOF));
 
-            // Otherwise, try to read more data and try again. Make sure we've got room
+            // Otherwise, try to read more data and try again. Make sure we've got room.
             let remaining = this.read_buf.capacity() - this.read_buf.len();
             if remaining < LW {
                 this.read_buf.reserve(HW - remaining)
@@ -341,13 +335,12 @@ where
 }
 
 impl<T, U> Framed<T, U> {
-    /// This function returns a *single* object that is both `Stream` and
+    /// This function returns a *single* object that is both `Stream` and `Sink`; grouping this into
-    /// `Sink`; grouping this into a single object is often useful for layering
+    /// a single object is often useful for layering things like gzip or TLS, which require both
-    /// things like gzip or TLS, which require both read and write access to the
+    /// read and write access to the underlying object.
-    /// underlying object.
     ///
-    /// These objects take a stream, a read buffer and a write buffer. These
+    /// These objects take a stream, a read buffer and a write buffer. These fields can be obtained
-    /// fields can be obtained from an existing `Framed` with the `into_parts` method.
+    /// from an existing `Framed` with the `into_parts` method.
     pub fn from_parts(parts: FramedParts<T, U>) -> Framed<T, U> {
         Framed {
             io: parts.io,
@@ -358,12 +351,11 @@ impl<T, U> Framed<T, U> {
         }
     }
 
-    /// Consumes the `Frame`, returning its underlying I/O stream, the buffer
+    /// Consumes the `Frame`, returning its underlying I/O stream, the buffer with unprocessed data,
-    /// with unprocessed data, and the codec.
+    /// and the codec.
     ///
-    /// Note that care should be taken to not tamper with the underlying stream
+    /// Note that care should be taken to not tamper with the underlying stream of data coming in as
-    /// of data coming in as it may corrupt the stream of frames otherwise
+    /// it may corrupt the stream of frames otherwise being worked with.
-    /// being worked with.
     pub fn into_parts(self) -> FramedParts<T, U> {
         FramedParts {
             io: self.io,
@@ -376,14 +368,15 @@ impl<T, U> Framed<T, U> {
 }
 
 /// `FramedParts` contains an export of the data of a Framed transport.
-/// It can be used to construct a new `Framed` with a different codec.
+///
-/// It contains all current buffers and the inner transport.
+/// It can be used to construct a new `Framed` with a different codec. It contains all current
+/// buffers and the inner transport.
 #[derive(Debug)]
 pub struct FramedParts<T, U> {
-    /// The inner transport used to read bytes to and write bytes to
+    /// The inner transport used to read bytes to and write bytes to.
     pub io: T,
 
-    /// The codec
+    /// The codec object.
     pub codec: U,
 
     /// The buffer with read but unprocessed data.
@@ -396,7 +389,7 @@ pub struct FramedParts<T, U> {
 }
 
 impl<T, U> FramedParts<T, U> {
-    /// Create a new, default, `FramedParts`
+    /// Creates a new default `FramedParts`.
     pub fn new(io: T, codec: U) -> FramedParts<T, U> {
         FramedParts {
             io,
@@ -407,7 +400,7 @@ impl<T, U> FramedParts<T, U> {
         }
     }
 
-    /// Create a new `FramedParts` with read buffer
+    /// Creates a new `FramedParts` with read buffer.
     pub fn with_read_buf(io: T, codec: U, read_buf: BytesMut) -> FramedParts<T, U> {
         FramedParts {
             io,