From 0a506bf2e9f0d07c505df725a68808c6343f7a4e Mon Sep 17 00:00:00 2001 From: Rob Ede Date: Fri, 15 Jan 2021 05:38:50 +0000 Subject: [PATCH] cleanup top level doc comments --- actix-http/src/client/config.rs | 5 +- actix-http/src/client/h2proto.rs | 2 +- actix-http/src/config.rs | 2 +- actix-http/src/error.rs | 1 - .../src/header/common/content_disposition.rs | 14 ++--- actix-http/src/header/mod.rs | 4 +- actix-http/src/ws/mask.rs | 8 +-- actix-http/src/ws/mod.rs | 6 --- awc/tests/test_client.rs | 5 ++ awc/tests/test_rustls_client.rs | 1 + src/app_service.rs | 4 +- src/handler.rs | 2 +- src/middleware/compat.rs | 3 +- src/types/json.rs | 2 +- src/types/payload.rs | 2 +- tests/test_server.rs | 26 +--------- tests/test_weird_poll.rs | 52 +++++++++---------- 17 files changed, 57 insertions(+), 82 deletions(-) diff --git a/actix-http/src/client/config.rs b/actix-http/src/client/config.rs index c86c697a..36973296 100644 --- a/actix-http/src/client/config.rs +++ b/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_STREAM_WINDOW: u32 = 1024 * 1024; // 1mb +const DEFAULT_H2_CONN_WINDOW: u32 = 1024 * 1024 * 2; // 2MB +const DEFAULT_H2_STREAM_WINDOW: u32 = 1024 * 1024; // 1MB /// Connector configuration #[derive(Clone)] diff --git a/actix-http/src/client/h2proto.rs b/actix-http/src/client/h2proto.rs index 4c609ef2..76915f21 100644 --- a/actix-http/src/client/h2proto.rs +++ b/actix-http/src/client/h2proto.rs @@ -171,7 +171,7 @@ async fn send_body( } } -// release SendRequest object +/// release SendRequest object fn release( io: SendRequest, pool: Option>, diff --git a/actix-http/src/config.rs b/actix-http/src/config.rs index 1cd7e4ae..f178db27 100644 --- a/actix-http/src/config.rs +++ b/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)] diff --git a/actix-http/src/error.rs b/actix-http/src/error.rs index a585962b..9ff15424 100644 --- a/actix-http/src/error.rs +++ b/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; diff --git a/actix-http/src/header/common/content_disposition.rs b/actix-http/src/header/common/content_disposition.rs index ae4a9790..ecc59aba 100644 --- a/actix-http/src/header/common/content_disposition.rs +++ b/actix-http/src/header/common/content_disposition.rs @@ -1,10 +1,10 @@ -// # References -// -// "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 -// "Returning Values from Forms: multipart/form-data" https://www.ietf.org/rfc/rfc7578.txt -// Browser conformance tests at: http://greenbytes.de/tech/tc2231/ -// IANA assignment: http://www.iana.org/assignments/cont-disp/cont-disp.xhtml +//! # References +//! +//! "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 +//! "Returning Values from Forms: multipart/form-data" https://www.ietf.org/rfc/rfc7578.txt +//! Browser conformance tests at: http://greenbytes.de/tech/tc2231/ +//! IANA assignment: http://www.iana.org/assignments/cont-disp/cont-disp.xhtml use lazy_static::lazy_static; use regex::Regex; diff --git a/actix-http/src/header/mod.rs b/actix-http/src/header/mod.rs index e4e15cd9..dc97bf5f 100644 --- a/actix-http/src/header/mod.rs +++ b/actix-http/src/header/mod.rs @@ -80,8 +80,8 @@ impl From for HeaderMap { } } -// This encode set is used for HTTP header values and is defined at -// https://tools.ietf.org/html/rfc5987#section-3.2. +/// This encode set is used for HTTP header values and is defined at +/// https://tools.ietf.org/html/rfc5987#section-3.2. pub(crate) const HTTP_VALUE: &AsciiSet = &CONTROLS .add(b' ') .add(b'"') diff --git a/actix-http/src/ws/mask.rs b/actix-http/src/ws/mask.rs index d37d57eb..79e015f7 100644 --- a/actix-http/src/ws/mask.rs +++ 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 -// u64 mid section. +/// Splits a slice into three parts: +/// - 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; diff --git a/actix-http/src/ws/mod.rs b/actix-http/src/ws/mod.rs index f8142693..dad2646c 100644 --- a/actix-http/src/ws/mod.rs +++ b/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 { 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 { diff --git a/awc/tests/test_client.rs b/awc/tests/test_client.rs index c3192156..3f5bf295 100644 --- a/awc/tests/test_client.rs +++ b/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(); diff --git a/awc/tests/test_rustls_client.rs b/awc/tests/test_rustls_client.rs index 3fa76d4a..2f5ffeca 100644 --- a/awc/tests/test_rustls_client.rs +++ b/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)); diff --git a/src/app_service.rs b/src/app_service.rs index 8169be51..4c099d4a 100644 --- a/src/app_service.rs +++ b/src/app_service.rs @@ -149,7 +149,7 @@ where } } -/// Service to convert `Request` to a `ServiceRequest` +/// Service that takes a [`Request`] and delegates to a service that take a [`ServiceRequest`]. pub struct AppInitService where T: Service, Error = Error>, @@ -159,7 +159,7 @@ where app_state: Rc, } -// 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, config: AppConfig, diff --git a/src/handler.rs b/src/handler.rs index 47656cd8..1526f050 100644 --- a/src/handler.rs +++ b/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 Service for HandlerService where F: Handler, diff --git a/src/middleware/compat.rs b/src/middleware/compat.rs index eabd1190..d5661fc7 100644 --- a/src/middleware/compat.rs +++ b/src/middleware/compat.rs @@ -110,8 +110,7 @@ where } } -// trait for convert ServiceResponse's ResponseBody generic type -// to ResponseBody +/// Convert `ServiceResponse`'s `ResponseBody` generic type to `ResponseBody`. pub trait MapServiceResponseBody { fn map_body(self) -> ServiceResponse; } diff --git a/src/types/json.rs b/src/types/json.rs index 7b94f66f..41618b40 100644 --- a/src/types/json.rs +++ b/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, diff --git a/src/types/payload.rs b/src/types/payload.rs index bee1b695..ad0bfd14 100644 --- a/src/types/payload.rs +++ b/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, diff --git a/tests/test_server.rs b/tests/test_server.rs index e8735966..7756d44d 100644 --- a/tests/test_server.rs +++ b/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()); -// } diff --git a/tests/test_weird_poll.rs b/tests/test_weird_poll.rs index 7e430090..5844ea2c 100644 --- a/tests/test_weird_poll.rs +++ b/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 futures::task::{noop_waker, Context}; -use futures::stream::once; -use actix_http::body::{MessageBody, BodyStream}; -use bytes::Bytes; +// use actix_http::body::{BodyStream, MessageBody}; +// use bytes::Bytes; +// use futures_channel::oneshot; +// use futures_util::{ +// 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] -fn weird_poll() { - 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 mut cx = Context::from_waker(&waker); - let waker = noop_waker(); - let mut context = Context::from_waker(&waker); - - let _ = body_stream.as_mut().unwrap().poll_next(&mut context); - sender.send(()).unwrap(); - let _ = std::mem::replace(&mut body_stream, Err([0; 32])).unwrap().poll_next(&mut context); -} - -*/ +// let _ = body_stream.as_mut().unwrap().poll_next(&mut cx); +// sender.send(()).unwrap(); +// let _ = std::mem::replace(&mut body_stream, Err([0; 32])) +// .unwrap() +// .poll_next(&mut cx); +// }