Use the unstable #[doc(cfg)] to document the tokio feature

rust-lang/rust#43781

Author: asomers

.cirrus.yml

@@ -22,6 +22,10 @@ test_task:
     -   cargo test
     - fi
     - cargo test --no-default-features
+  doc_script:
+    - if rustc --version | grep -q nightly; then
+    -   cargo doc --all-features --no-deps
+    - fi
   before_cache_script: rm -rf $CARGO_HOME/registry/index
 
 codecov_task:

CHANGELOG.md

@@ -1,4 +1,9 @@
-## 0.3.1 - 2018-12-26
+## [Unreleased] - ReleaseDate
+### Changed
+- Better documentation
+  ([#15](https://github.com/asomers/futures-locks/pull/15))
+
+## [0.3.1] - 2018-12-26
 ### Changed
 - Minimum compiler version has increased to 1.31.0
   ([#10](https://github.com/asomers/futures-locks/pull/10))

Cargo.toml

@@ -19,6 +19,9 @@ autotests = false
 
 [features]
 default = ["tokio"]
+# For building documentation only; no functional change to the library.
+nightly-docs = []
+# Enable methods that require a Tokio executor.
 tokio = ["tokio-current-thread", "tokio-executor"]
 
 [dependencies]

src/lib.rs

@@ -7,6 +7,8 @@
 //! [`Futures`]: https://github.com/rust-lang-nursery/futures-rs
 //! [`Tokio`]: https:/tokio.rs
 
+#![cfg_attr(feature = "nightly-docs", feature(doc_cfg))]
+
 extern crate futures;
 #[cfg(feature = "tokio")] extern crate tokio_current_thread;
 #[cfg(feature = "tokio")] extern crate tokio_executor;

src/mutex.rs

@@ -295,9 +295,6 @@ impl<T: 'static + ?Sized> Mutex<T> {
     /// separate task.  Returns a `Future` containing the result of the
     /// computation.
     ///
-    /// *This method requires Futures-locks to be build with the `"tokio"`
-    /// feature.*
-    ///
     /// When using Tokio, this method will often hold the `Mutex` for less time
     /// than chaining a computation to [`lock`](#method.lock).  The reason is
     /// that Tokio polls all tasks promptly upon notification.  However, Tokio
@@ -328,7 +325,8 @@ impl<T: 'static + ?Sized> Mutex<T> {
     /// assert_eq!(mtx.try_unwrap().unwrap(), 5);
     /// # }
     /// ```
-    #[cfg(feature = "tokio")]
+    #[cfg(any(feature = "tokio", all(feature = "nightly-docs", rustdoc)))]
+    #[cfg_attr(feature = "nightly-docs", doc(cfg(feature = "tokio")))]
     pub fn with<F, B, R, E>(&self, f: F)
         -> Result<impl Future<Item = R, Error = E>, SpawnError>
         where F: FnOnce(MutexGuard<T>) -> B + Send + 'static,
@@ -357,9 +355,6 @@ impl<T: 'static + ?Sized> Mutex<T> {
     /// Like [`with`](#method.with) but for Futures that aren't `Send`.
     /// Spawns a new task on a single-threaded Runtime to complete the Future.
     ///
-    /// *This method requires Futures-locks to be build with the `"tokio"`
-    /// feature.*
-    ///
     /// # Examples
     ///
     /// ```
@@ -384,7 +379,8 @@ impl<T: 'static + ?Sized> Mutex<T> {
     /// assert_eq!(*mtx.try_unwrap().unwrap(), 5);
     /// # }
     /// ```
-    #[cfg(feature = "tokio")]
+    #[cfg(any(feature = "tokio", all(feature = "nightly-docs", rustdoc)))]
+    #[cfg_attr(feature = "nightly-docs", doc(cfg(feature = "tokio")))]
     pub fn with_local<F, B, R, E>(&self, f: F)
         -> Result<impl Future<Item = R, Error = E>, SpawnError>
         where F: FnOnce(MutexGuard<T>) -> B + 'static,

src/rwlock.rs

@@ -489,9 +489,6 @@ impl<T: 'static + ?Sized> RwLock<T> {
     /// guarded value in a separate task.  Returns a `Future` containing the
     /// result of the computation.
     ///
-    /// *This method requires Futures-locks to be build with the `"tokio"`
-    /// feature.*
-    ///
     /// When using Tokio, this method will often hold the `RwLock` for less time
     /// than chaining a computation to [`read`](#method.read).  The reason is
     /// that Tokio polls all tasks promptly upon notification.  However, Tokio
@@ -520,7 +517,8 @@ impl<T: 'static + ?Sized> RwLock<T> {
     /// assert_eq!(r, Ok(5));
     /// # }
     /// ```
-    #[cfg(feature = "tokio")]
+    #[cfg(any(feature = "tokio", all(feature = "nightly-docs", rustdoc)))]
+    #[cfg_attr(feature = "nightly-docs", doc(cfg(feature = "tokio")))]
     pub fn with_read<F, B, R, E>(&self, f: F)
         -> Result<impl Future<Item = R, Error = E>, SpawnError>
         where F: FnOnce(RwLockReadGuard<T>) -> B + Send + 'static,
@@ -550,9 +548,6 @@ impl<T: 'static + ?Sized> RwLock<T> {
     /// `Send`.  Spawns a new task on a single-threaded Runtime to complete the
     /// Future.
     ///
-    /// *This method requires Futures-locks to be build with the `"tokio"`
-    /// feature.*
-    ///
     /// # Examples
     ///
     /// ```
@@ -575,7 +570,8 @@ impl<T: 'static + ?Sized> RwLock<T> {
     /// assert_eq!(r, Ok(5));
     /// # }
     /// ```
-    #[cfg(feature = "tokio")]
+    #[cfg(any(feature = "tokio", all(feature = "nightly-docs", rustdoc)))]
+    #[cfg_attr(feature = "nightly-docs", doc(cfg(feature = "tokio")))]
     pub fn with_read_local<F, B, R, E>(&self, f: F)
         -> Result<impl Future<Item = R, Error = E>, SpawnError>
         where F: FnOnce(RwLockReadGuard<T>) -> B + 'static,
@@ -604,9 +600,6 @@ impl<T: 'static + ?Sized> RwLock<T> {
     /// guarded value in a separate task.  Returns a `Future` containing the
     /// result of the computation.
     ///
-    /// *This method requires Futures-locks to be build with the `"tokio"`
-    /// feature.*
-    ///
     /// When using Tokio, this method will often hold the `RwLock` for less time
     /// than chaining a computation to [`write`](#method.write).  The reason is
     /// that Tokio polls all tasks promptly upon notification.  However, Tokio
@@ -637,7 +630,8 @@ impl<T: 'static + ?Sized> RwLock<T> {
     /// assert_eq!(rwlock.try_unwrap().unwrap(), 5);
     /// # }
     /// ```
-    #[cfg(feature = "tokio")]
+    #[cfg(any(feature = "tokio", all(feature = "nightly-docs", rustdoc)))]
+    #[cfg_attr(feature = "nightly-docs", doc(cfg(feature = "tokio")))]
     pub fn with_write<F, B, R, E>(&self, f: F)
         -> Result<impl Future<Item = R, Error = E>, SpawnError>
         where F: FnOnce(RwLockWriteGuard<T>) -> B + Send + 'static,
@@ -667,9 +661,6 @@ impl<T: 'static + ?Sized> RwLock<T> {
     /// `Send`.  Spawns a new task on a single-threaded Runtime to complete the
     /// Future.
     ///
-    /// *This method requires Futures-locks to be build with the `"tokio"`
-    /// feature.*
-    ///
     /// # Examples
     ///
     /// ```
@@ -694,7 +685,8 @@ impl<T: 'static + ?Sized> RwLock<T> {
     /// assert_eq!(*rwlock.try_unwrap().unwrap(), 5);
     /// # }
     /// ```
-    #[cfg(feature = "tokio")]
+    #[cfg(any(feature = "tokio", all(feature = "nightly-docs", rustdoc)))]
+    #[cfg_attr(feature = "nightly-docs", doc(cfg(feature = "tokio")))]
     pub fn with_write_local<F, B, R, E>(&self, f: F)
         -> Result<impl Future<Item = R, Error = E>, SpawnError>
         where F: FnOnce(RwLockWriteGuard<T>) -> B + 'static,