Fixing documentation issues

Also making CI run tests across the workspace

.github/workflows/docs.yml

@@ -14,7 +14,7 @@ jobs:
       - uses: actions/checkout@v3
       - name: Generate Docs
         run: |
-          cargo +nightly doc --no-deps --all-features
+          cargo +nightly doc --no-deps --all-features --workspace
 
       - name: Deploy Docs
         if: github.ref == 'refs/heads/main'

.github/workflows/rust.yml

@@ -14,11 +14,11 @@ jobs:
 
       - name: Run clippy
         run: |
-          cargo clippy
+          cargo clippy --workspace
 
       - name: Run unit tests
         run: |
-          cargo test --all-targets
+          cargo test --workspace
 
   miri:
     runs-on: ubuntu-latest
@@ -48,4 +48,4 @@ jobs:
         with:
           rust-version: 1.73
       - name: Run unit tests
-        run: cargo test --all-targets
+        run: cargo test --workspace

refuse-pool/src/lib.rs

@@ -13,27 +13,25 @@
 //! use refuse::CollectionGuard;
 //! use refuse_pool::{RefString, RootString};
 //!
-//! refuse::collected(|| {
-//!     let a = RootString::from("a");
-//!     let a_again = RootString::from(String::from("a"));
+//! let a = RootString::from("a");
+//! let a_again = RootString::from(String::from("a"));
 //!
-//!     // Both a and a_again point to the same underlying storage.
-//!     assert_eq!(a.root_count(), 2);
-//!     // Comparing two RootStrings is cheap.
-//!     assert_eq!(a, a_again);
+//! // Both a and a_again point to the same underlying storage.
+//! assert_eq!(a.root_count(), 2);
+//! // Comparing two RootStrings is cheap.
+//! assert_eq!(a, a_again);
 //!
-//!     // a_ref can be used to gain a reference to a string,
-//!     // but only until the string is unreachable.
-//!     let a_ref = a.downgrade();
+//! // a_ref can be used to gain a reference to a string,
+//! // but only until the string is unreachable.
+//! let a_ref = a.downgrade();
 //!
-//!     let mut guard = CollectionGuard::acquire();
-//!     assert_eq!(a_ref.load(&guard), Some("a"));
+//! let mut guard = CollectionGuard::acquire();
+//! assert_eq!(a_ref.load(&guard), Some("a"));
 //!
-//!     drop(a);
-//!     drop(a_again);
-//!     guard.collect();
-//!     assert_eq!(a_ref.load(&guard), None);
-//! });
+//! drop(a);
+//! drop(a_again);
+//! guard.collect();
+//! assert_eq!(a_ref.load(&guard), None);
 //! ```
 //!
 //! [refuse]: https://github.com/khonsulabs/refuse

src/lib.rs

@@ -914,10 +914,8 @@ impl CollectionGuard<'static> {
     /// This guard is used to provide read-only access to garbage collected
     /// allocations.
     ///
-    /// # Panics
-    ///
-    /// A panic will occur if this function is called outside of code executed
-    /// by [`collected()`].
+    /// It is safe to acquire multiple guards on the same thread. The collector
+    /// will only be able to run when all guards have been released.
     #[must_use]
     pub fn acquire() -> Self {
         let thread = ThreadPool::get();
@@ -935,15 +933,17 @@ impl CollectionGuard<'static> {
         }
     }
 
-    /// Acquires a lock that prevents the garbage collector from running.
+    /// Tries to acquire a lock that prevents the garbage collector from
+    /// running.
+    ///
+    /// The function will return None if the collector is attempting to run
+    /// garbage collection, and this thread is not already guarded.
     ///
     /// This guard is used to provide read-only access to garbage collected
     /// allocations.
     ///
-    /// # Panics
-    ///
-    /// A panic will occur if this function is called outside of code executed
-    /// by [`collected()`].
+    /// It is safe to acquire multiple guards on the same thread. The collector
+    /// will only be able to run when all guards have been released.
     #[must_use]
     pub fn try_acquire() -> Option<Self> {
         let thread = ThreadPool::get();