cleanup top level doc comments

actix-http/src/client/config.rs

@@ -1,8 +1,7 @@
 use std::time::Duration;
 
-// These values are taken from hyper/src/proto/h2/client.rs
+const DEFAULT_H2_CONN_WINDOW: u32 = 1024 * 1024 * 2; // 2MB
-const DEFAULT_H2_CONN_WINDOW: u32 = 1024 * 1024 * 2; // 2mb
+const DEFAULT_H2_STREAM_WINDOW: u32 = 1024 * 1024; // 1MB
-const DEFAULT_H2_STREAM_WINDOW: u32 = 1024 * 1024; // 1mb
 
 /// Connector configuration
 #[derive(Clone)]

actix-http/src/client/h2proto.rs

@@ -171,7 +171,7 @@ async fn send_body<B: MessageBody>(
     }
 }
 
-// release SendRequest object
+/// release SendRequest object
 fn release<T: AsyncRead + AsyncWrite + Unpin + 'static>(
     io: SendRequest<Bytes>,
     pool: Option<Acquired<T>>,

actix-http/src/config.rs

@@ -9,7 +9,7 @@ use bytes::BytesMut;
 use futures_util::{future, FutureExt};
 use time::OffsetDateTime;
 
-// "Sun, 06 Nov 1994 08:49:37 GMT".len()
+/// "Sun, 06 Nov 1994 08:49:37 GMT".len()
 const DATE_VALUE_LENGTH: usize = 29;
 
 #[derive(Debug, PartialEq, Clone, Copy)]

actix-http/src/error.rs

@@ -18,7 +18,6 @@ use serde::de::value::Error as DeError;
 use serde_json::error::Error as JsonError;
 use serde_urlencoded::ser::Error as FormError;
 
-// re-export for convenience
 use crate::body::Body;
 pub use crate::cookie::ParseError as CookieParseError;
 use crate::helpers::Writer;

actix-http/src/header/common/content_disposition.rs

@@ -1,10 +1,10 @@
-// # References
+//! # References
-//
+//!
-// "The Content-Disposition Header Field" https://www.ietf.org/rfc/rfc2183.txt
+//! "The Content-Disposition Header Field" https://www.ietf.org/rfc/rfc2183.txt
-// "The Content-Disposition Header Field in the Hypertext Transfer Protocol (HTTP)" https://www.ietf.org/rfc/rfc6266.txt
+//! "The Content-Disposition Header Field in the Hypertext Transfer Protocol (HTTP)" https://www.ietf.org/rfc/rfc6266.txt
-// "Returning Values from Forms: multipart/form-data" https://www.ietf.org/rfc/rfc7578.txt
+//! "Returning Values from Forms: multipart/form-data" https://www.ietf.org/rfc/rfc7578.txt
-// Browser conformance tests at: http://greenbytes.de/tech/tc2231/
+//! Browser conformance tests at: http://greenbytes.de/tech/tc2231/
-// IANA assignment: http://www.iana.org/assignments/cont-disp/cont-disp.xhtml
+//! IANA assignment: http://www.iana.org/assignments/cont-disp/cont-disp.xhtml
 
 use lazy_static::lazy_static;
 use regex::Regex;

actix-http/src/header/mod.rs

@@ -80,8 +80,8 @@ impl From<http::HeaderMap> for HeaderMap {
     }
 }
 
-// This encode set is used for HTTP header values and is defined at
+/// This encode set is used for HTTP header values and is defined at
-// https://tools.ietf.org/html/rfc5987#section-3.2.
+/// https://tools.ietf.org/html/rfc5987#section-3.2.
 pub(crate) const HTTP_VALUE: &AsciiSet = &CONTROLS
     .add(b' ')
     .add(b'"')

actix-http/src/ws/mask.rs

@@ -3,7 +3,7 @@
 use std::ptr::copy_nonoverlapping;
 use std::slice;
 
-// Holds a slice guaranteed to be shorter than 8 bytes
+/// Holds a slice guaranteed to be shorter than 8 bytes.
 struct ShortSlice<'a> {
     inner: &'a mut [u8],
 }
@@ -80,8 +80,10 @@ unsafe fn cast_slice(buf: &mut [u8]) -> &mut [u64] {
     slice::from_raw_parts_mut(buf.as_mut_ptr() as *mut u64, buf.len() >> 3)
 }
 
-// Splits a slice into three parts: an unaligned short head and tail, plus an aligned
+/// Splits a slice into three parts:
-// u64 mid section.
+/// - an unaligned short head
+/// - an aligned `u64` slice mid section
+/// - an unaligned short tail
 #[inline]
 fn align_buf(buf: &mut [u8]) -> (ShortSlice<'_>, &mut [u64], ShortSlice<'_>) {
     let start_ptr = buf.as_ptr() as usize;

actix-http/src/ws/mod.rs

@@ -128,18 +128,12 @@ impl ResponseError for HandshakeError {
 }
 
 /// Verify `WebSocket` handshake request and create handshake response.
-// /// `protocols` is a sequence of known protocols. On successful handshake,
-// /// the returned response headers contain the first protocol in this list
-// /// which the server also knows.
 pub fn handshake(req: &RequestHead) -> Result<ResponseBuilder, HandshakeError> {
     verify_handshake(req)?;
     Ok(handshake_response(req))
 }
 
 /// Verify `WebSocket` handshake request.
-// /// `protocols` is a sequence of known protocols. On successful handshake,
-// /// the returned response headers contain the first protocol in this list
-// /// which the server also knows.
 pub fn verify_handshake(req: &RequestHead) -> Result<(), HandshakeError> {
     // WebSocket accepts only GET
     if req.method != Method::GET {

awc/tests/test_client.rs

@@ -557,6 +557,7 @@ async fn test_client_brotli_encoding_large_random() {
     assert_eq!(bytes, Bytes::from(data));
 }
 
+// TODO: why is test ignored
 // #[actix_rt::test]
 // async fn test_client_deflate_encoding() {
 //     let srv = test::TestServer::start(|app| {
@@ -585,6 +586,7 @@ async fn test_client_brotli_encoding_large_random() {
 //     assert_eq!(bytes, Bytes::from_static(STR.as_ref()));
 // }
 
+// TODO: why is test ignored
 // #[actix_rt::test]
 // async fn test_client_deflate_encoding_large_random() {
 //     let data = rand::thread_rng()
@@ -618,6 +620,7 @@ async fn test_client_brotli_encoding_large_random() {
 //     assert_eq!(bytes, Bytes::from(data));
 // }
 
+// TODO: why is test ignored
 // #[actix_rt::test]
 // async fn test_client_streaming_explicit() {
 //     let srv = test::TestServer::start(|app| {
@@ -645,6 +648,7 @@ async fn test_client_brotli_encoding_large_random() {
 //     assert_eq!(bytes, Bytes::from_static(STR.as_ref()));
 // }
 
+// TODO: why is test ignored
 // #[actix_rt::test]
 // async fn test_body_streaming_implicit() {
 //     let srv = test::TestServer::start(|app| {
@@ -734,6 +738,7 @@ async fn test_client_cookie_handling() {
     assert_eq!(c2, cookie2);
 }
 
+// TODO: why is test ignored
 // #[actix_rt::test]
 // fn client_read_until_eof() {
 //     let addr = test::TestServer::unused_addr();

awc/tests/test_rustls_client.rs

@@ -50,6 +50,7 @@ mod danger {
     }
 }
 
+// TODO: why is test ignored
 // #[actix_rt::test]
 async fn _test_connection_reuse_h2() {
     let num = Arc::new(AtomicUsize::new(0));

src/app_service.rs

@@ -149,7 +149,7 @@ where
     }
 }
 
-/// Service to convert `Request` to a `ServiceRequest<S>`
+/// Service that takes a [`Request`] and delegates to a service that take a [`ServiceRequest`].
 pub struct AppInitService<T, B>
 where
     T: Service<ServiceRequest, Response = ServiceResponse<B>, Error = Error>,
@@ -159,7 +159,7 @@ where
     app_state: Rc<AppInitServiceState>,
 }
 
-// a collection of AppInitService state that shared between HttpRequests.
+/// A collection of [`AppInitService`] state that shared across `HttpRequest`s.
 pub(crate) struct AppInitServiceState {
     rmap: Rc<ResourceMap>,
     config: AppConfig,

src/handler.rs

@@ -101,7 +101,7 @@ where
     }
 }
 
-// HandlerService is both it's ServiceFactory and Service Type.
+/// HandlerService is both it's ServiceFactory and Service Type.
 impl<F, T, R> Service<ServiceRequest> for HandlerService<F, T, R>
 where
     F: Handler<T, R>,

src/middleware/compat.rs

@@ -110,8 +110,7 @@ where
     }
 }
 
-// trait for convert ServiceResponse's ResponseBody<B> generic type
+/// Convert `ServiceResponse`'s `ResponseBody<B>` generic type to `ResponseBody<Body>`.
-// to ResponseBody<Body>
 pub trait MapServiceResponseBody {
     fn map_body(self) -> ServiceResponse;
 }

src/types/json.rs

@@ -269,7 +269,7 @@ impl JsonConfig {
     }
 }
 
-// Allow shared refs to default.
+/// Allow shared refs used as default.
 const DEFAULT_CONFIG: JsonConfig = JsonConfig {
     limit: 32_768, // 2^15 bytes, (~32kB)
     err_handler: None,

src/types/payload.rs

@@ -247,7 +247,7 @@ impl PayloadConfig {
     }
 }
 
-// Allow shared refs to default.
+/// Allow shared refs used as defaults.
 const DEFAULT_CONFIG: PayloadConfig = PayloadConfig {
     limit: DEFAULT_CONFIG_LIMIT,
     mimetype: None,

tests/test_server.rs

@@ -800,6 +800,7 @@ async fn test_reading_deflate_encoding_large_random_rustls() {
     assert_eq!(bytes, Bytes::from(data));
 }
 
+// TODO: why is test ignored
 // #[test]
 // fn test_server_cookies() {
 //     use actix_web::http;
@@ -889,28 +890,3 @@ async fn test_normalize() {
     let response = srv.get("/one/").send().await.unwrap();
     assert!(response.status().is_success());
 }
-
-// #[cfg(feature = "openssl")]
-// #[actix_rt::test]
-// async fn test_ssl_handshake_timeout() {
-//     use open_ssl::ssl::{SslAcceptor, SslFiletype, SslMethod};
-//     use std::net;
-
-//     // load ssl keys
-//     let mut builder = SslAcceptor::mozilla_intermediate(SslMethod::tls()).unwrap();
-//     builder
-//         .set_private_key_file("tests/key.pem", SslFiletype::PEM)
-//         .unwrap();
-//     builder
-//         .set_certificate_chain_file("tests/cert.pem")
-//         .unwrap();
-
-//     let srv = test::start_with(test::config().openssl(builder.build()), || {
-//         App::new().service(web::resource("/").route(web::to(|| HttpResponse::Ok())))
-//     });
-
-//     let mut stream = net::TcpStream::connect(srv.addr()).unwrap();
-//     let mut data = String::new();
-//     let _ = stream.read_to_string(&mut data);
-//     assert!(data.is_empty());
-// }

tests/test_weird_poll.rs

@@ -1,30 +1,30 @@
-// Regression test for #/1321
+//! Regression test for https://github.com/actix/actix-web/issues/1321
 
-/*
+// use actix_http::body::{BodyStream, MessageBody};
-use futures::task::{noop_waker, Context};
+// use bytes::Bytes;
-use futures::stream::once;
+// use futures_channel::oneshot;
-use actix_http::body::{MessageBody, BodyStream};
+// use futures_util::{
-use bytes::Bytes;
+//     stream::once,
+//     task::{noop_waker, Context},
+// };
 
-Disable weird poll until actix-web is based on actix-http 2.0.0
+// #[test]
+// fn weird_poll() {
+//     let (sender, receiver) = oneshot::channel();
+//     let mut body_stream = Ok(BodyStream::new(once(async {
+//         let x = Box::new(0);
+//         let y = &x;
+//         receiver.await.unwrap();
+//         let _z = **y;
+//         Ok::<_, ()>(Bytes::new())
+//     })));
 
-#[test]
+//     let waker = noop_waker();
-fn weird_poll() {
+//     let mut cx = Context::from_waker(&waker);
-    let (sender, receiver) = futures::channel::oneshot::channel();
-    let mut body_stream = Ok(BodyStream::new(once(async {
-        let x = Box::new(0);
-        let y = &x;
-        receiver.await.unwrap();
-        let _z = **y;
-        Ok::<_, ()>(Bytes::new())
-    })));
 
-    let waker = noop_waker();
+//     let _ = body_stream.as_mut().unwrap().poll_next(&mut cx);
-    let mut context = Context::from_waker(&waker);
+//     sender.send(()).unwrap();
-
+//     let _ = std::mem::replace(&mut body_stream, Err([0; 32]))
-    let _ = body_stream.as_mut().unwrap().poll_next(&mut context);
+//         .unwrap()
-    sender.send(()).unwrap();
+//         .poll_next(&mut cx);
-    let _ = std::mem::replace(&mut body_stream, Err([0; 32])).unwrap().poll_next(&mut context);
+// }
-}
-
-*/