Put Client + Server behind "unstable" flag

Author: yoshuawuyts

Cargo.toml

@@ -11,8 +11,13 @@ authors = ["Yoshua Wuyts <[email protected]>"]
 readme = "README.md"
 edition = "2018"
 
+[package.metadata.docs.rs]
+features = ["docs"]
+rustdoc-args = ["--cfg", "feature=\"docs\""]
+
 [features]
 default = []
+docs = ["unstable"]
 unstable = []
 hyperium_http = ["http"]
 

src/client.rs

@@ -7,6 +7,8 @@ use crate::{Request, Response, Result};
 type BoxFuture<'a, T> = Pin<Box<dyn Future<Output = T> + 'a + Send>>;
 
 /// An HTTP client.
+#[cfg(feature = "unstable")]
+#[cfg_attr(feature = "docs", doc(cfg(unstable)))]
 pub trait Client: Debug + Unpin + Send + Sync + Clone + 'static {
     /// Send an HTTP request from the client.
     fn send_req(&self, req: Request) -> BoxFuture<'static, Result<Response>>;

src/lib.rs

@@ -95,8 +95,9 @@
 
 #![forbid(rust_2018_idioms)]
 #![deny(missing_debug_implementations, nonstandard_style)]
-#![warn(missing_docs, missing_doc_code_examples, unreachable_pub)]
+#![warn(missing_docs, unreachable_pub)]
 #![cfg_attr(test, deny(warnings))]
+#![cfg_attr(feature = "docs", feature(doc_cfg))]
 
 /// HTTP cookies.
 pub mod cookies {
@@ -111,29 +112,36 @@ pub mod url {
     };
 }
 
+#[macro_use]
+mod utils;
+
 pub mod headers;
 pub mod mime;
 
 mod body;
-mod client;
 mod error;
 mod macros;
 mod method;
 mod request;
 mod response;
-mod server;
 mod status;
 mod status_code;
 mod type_map;
 mod version;
 
+cfg_unstable! {
+    mod client;
+    mod server;
+
+    pub use client::Client;
+    pub use server::Server;
+}
+
 pub use body::Body;
-pub use client::Client;
 pub use error::{Error, Result};
 pub use method::Method;
 pub use request::Request;
 pub use response::Response;
-pub use server::Server;
 pub use status::Status;
 pub use status_code::StatusCode;
 pub use version::Version;

src/request.rs

@@ -2,7 +2,6 @@ use async_std::io::{self, BufRead, Read};
 use async_std::sync;
 
 use std::convert::TryInto;
-use std::future::Future;
 use std::mem;
 use std::pin::Pin;
 use std::task::{Context, Poll};
@@ -14,9 +13,14 @@ use crate::mime::Mime;
 use crate::trailers::{Trailers, TrailersSender};
 use crate::Cookie;
 use crate::{Body, Method, TypeMap, Url, Version};
-use crate::{Client, Error, Response, Server};
 
-type BoxFuture<'a, T> = Pin<Box<dyn Future<Output = T> + 'a + Send>>;
+cfg_unstable! {
+    use std::future::Future;
+
+    use crate::{Client, Error, Response, Server};
+
+    type BoxFuture<'a, T> = Pin<Box<dyn Future<Output = T> + 'a + Send>>;
+}
 
 pin_project_lite::pin_project! {
     /// An HTTP request.
@@ -448,13 +452,17 @@ impl Request {
     /// This is useful for sending a request to a server without needing to
     /// make any further HTTP requests. Examples include: HTTP endpoints in
     /// frameworks, or testing logic for requests.
+    #[cfg(feature = "unstable")]
+    #[cfg_attr(feature = "docs", doc(cfg(unstable)))]
     pub fn send_to<S: Server>(self, server: &S) -> BoxFuture<'static, Result<Response, Error>> {
         server.recv_req(self)
     }
 
     /// Send a request through a client.
     ///
     /// This will most likely create an HTTP request over the network.
+    #[cfg(feature = "unstable")]
+    #[cfg_attr(feature = "docs", doc(cfg(unstable)))]
     pub fn send_from<C: Client>(self, client: &C) -> BoxFuture<'static, Result<Response, Error>> {
         client.send_req(self)
     }

src/server.rs

@@ -7,6 +7,8 @@ use crate::{Request, Response, Result};
 type BoxFuture<'a, T> = Pin<Box<dyn Future<Output = T> + 'a + Send>>;
 
 /// An HTTP server.
+#[cfg(feature = "unstable")]
+#[cfg_attr(feature = "docs", doc(cfg(unstable)))]
 pub trait Server: Debug + Unpin + Send + Sync + Clone + 'static {
     /// Receive an HTTP request on the server.
     fn recv_req(&self, req: Request) -> BoxFuture<'static, Result<Response>>;

src/utils.rs

@@ -0,0 +1,11 @@
+/// Declares unstable items.
+#[doc(hidden)]
+macro_rules! cfg_unstable {
+    ($($item:item)*) => {
+        $(
+            #[cfg(feature = "unstable")]
+            #[cfg_attr(feature = "docs", doc(cfg(unstable)))]
+            $item
+        )*
+    }
+}