From aa9ba2796b5ed2f2510d7ca3b0e9d04e9b2bdcc8 Mon Sep 17 00:00:00 2001 From: Chrislearn Young Date: Fri, 30 Aug 2024 07:40:46 +0800 Subject: [PATCH] doc: Update doc format `SecureMaxSize` doc --- crates/core/src/conn/acme/cache.rs | 11 ++++++----- crates/core/src/depot.rs | 2 +- crates/core/src/http/body/channel.rs | 2 +- crates/core/src/http/request.rs | 18 +++++++++++++++--- crates/extra/src/caching_headers.rs | 2 +- crates/extra/src/websocket.rs | 4 ++-- crates/oapi/docs/derive_to_response.md | 2 +- crates/oapi/docs/derive_to_schema.md | 2 +- crates/oapi/src/swagger_ui/config.rs | 2 +- 9 files changed, 29 insertions(+), 16 deletions(-) diff --git a/crates/core/src/conn/acme/cache.rs b/crates/core/src/conn/acme/cache.rs index a9fb15261..97d0efdcd 100644 --- a/crates/core/src/conn/acme/cache.rs +++ b/crates/core/src/conn/acme/cache.rs @@ -1,8 +1,9 @@ -/*! Ways to cache account data and certificates. -A default implementation for `AsRef` (`Sting`, `OsString`, `PathBuf`, ...) -allows the use of a local directory as cache. -Note that the files contain private keys. -*/ +//! Ways to cache account data and certificates. +//! A default implementation for `AsRef` (`Sting`, `OsString`, `PathBuf`, ...) +//! allows the use of a local directory as cache. +//! +//! **Note**: The files contain private keys. + use std::error::Error as StdError; use std::future::Future; diff --git a/crates/core/src/depot.rs b/crates/core/src/depot.rs index ef29de5ca..b1a0247ee 100644 --- a/crates/core/src/depot.rs +++ b/crates/core/src/depot.rs @@ -118,7 +118,7 @@ impl Depot { } /// Check is there a value is injected to the depot. /// - /// **Note: This is only check injected value.** + /// **Note**: This is only check injected value. #[inline] pub fn contains(&self) -> bool { self.map.contains_key(&type_key::()) diff --git a/crates/core/src/http/body/channel.rs b/crates/core/src/http/body/channel.rs index c3f9c542b..393d46e0d 100644 --- a/crates/core/src/http/body/channel.rs +++ b/crates/core/src/http/body/channel.rs @@ -13,7 +13,7 @@ use hyper::HeaderMap; /// /// ## Body Closing /// -/// Note that the request body will always be closed normally when the sender is dropped (meaning +/// **Note**: The request body will always be closed normally when the sender is dropped (meaning /// that the empty terminating chunk will be sent to the remote). If you desire to close the /// connection with an incomplete response (e.g. in the case of an error during asynchronous /// processing), call the [`Sender::abort()`] method to abort the body in an abnormal fashion. diff --git a/crates/core/src/http/request.rs b/crates/core/src/http/request.rs index caa7ccad3..226c404a4 100644 --- a/crates/core/src/http/request.rs +++ b/crates/core/src/http/request.rs @@ -32,21 +32,33 @@ use crate::{async_trait, Depot, Error, FlowCtrl, Handler}; static GLOBAL_SECURE_MAX_SIZE: RwLock = RwLock::new(64 * 1024); -/// Get global secure max size, default value is 64KB. +/// Get global secure maximum size, default value is 64KB. +/// +/// **Note**: The security maximum value is only effective when directly obtaining data +/// from the body. For uploaded files, the files are written to temporary files +/// and the bytes is not directly obtained, so they will not be affected. pub fn global_secure_max_size() -> usize { *GLOBAL_SECURE_MAX_SIZE.read() } -/// Set secure max size globally. +/// Set secure maximum size globally. /// /// It is recommended to use the [`SecureMaxSize`] middleware to have finer-grained /// control over [`Request`]. +/// +/// **Note**: The security maximum value is only effective when directly obtaining data +/// from the body. For uploaded files, the files are written to temporary files +/// and the bytes is not directly obtained, so they will not be affected. pub fn set_global_secure_max_size(size: usize) { let mut lock = GLOBAL_SECURE_MAX_SIZE.write(); *lock = size; } -/// Middleware for set the maximum size of request body. +/// Middleware for set the secure maximum size of request body. +/// +/// **Note**: The security maximum value is only effective when directly obtaining data +/// from the body. For uploaded files, the files are written to temporary files +/// and the bytes is not directly obtained, so they will not be affected. pub struct SecureMaxSize(pub usize); impl SecureMaxSize { /// Create a new `SecureMaxSize` instance. diff --git a/crates/extra/src/caching_headers.rs b/crates/extra/src/caching_headers.rs index 004bf44ea..bf477c2ef 100644 --- a/crates/extra/src/caching_headers.rs +++ b/crates/extra/src/caching_headers.rs @@ -22,7 +22,7 @@ use salvo_core::{async_trait, Depot, FlowCtrl, Handler, Request, Response}; /// /// ## Streamed bodies /// -/// Note that this handler does not currently provide an etag trailer for +/// **Note**: This handler does not currently provide an etag trailer for /// streamed bodies, but may do so in the future. /// /// ## Strong vs weak comparison diff --git a/crates/extra/src/websocket.rs b/crates/extra/src/websocket.rs index 2bec05c6c..9034355ee 100644 --- a/crates/extra/src/websocket.rs +++ b/crates/extra/src/websocket.rs @@ -151,11 +151,11 @@ impl WebSocketUpgrade { /// in the case the write buffer is filling up due to write errors. /// The default value is unlimited. /// - /// Note: The write buffer only builds up past [`write_buffer_size`](Self::write_buffer_size) + /// **Note**: The write buffer only builds up past [`write_buffer_size`](Self::write_buffer_size) /// when writes to the underlying stream are failing. So the **write buffer can not /// fill up if you are not observing write errors even if not flushing**. /// - /// Note: Should always be at least [`write_buffer_size + 1 message`](Self::write_buffer_size) + /// Should always be at least [`write_buffer_size + 1 message`](Self::write_buffer_size) /// and probably a little more depending on error handling strategy. #[inline] pub fn max_write_buffer_size(mut self, max: usize) -> Self { diff --git a/crates/oapi/docs/derive_to_response.md b/crates/oapi/docs/derive_to_response.md index ce0259b6e..4c499dc44 100644 --- a/crates/oapi/docs/derive_to_response.md +++ b/crates/oapi/docs/derive_to_response.md @@ -57,7 +57,7 @@ _`ToResponse`_ can be used in four different ways to generate OpenAPI response c 4. By decorating `enum` with variants having `#[salvo(content(...))]` attribute. This allows users to define multiple response content schemas to single response according to OpenAPI spec. - **Note!** Enum with _`content`_ attribute in variants cannot have enum level _`example`_ or + **Note**: Enum with _`content`_ attribute in variants cannot have enum level _`example`_ or _`examples`_ defined. Instead examples need to be defined per variant basis. Additionally these variants can also be used with `#[salvo(schema(...))]` attribute to inline the variant's type schema if it implements [`ToSchema`] derive macro. diff --git a/crates/oapi/docs/derive_to_schema.md b/crates/oapi/docs/derive_to_schema.md index a21b5a687..8d7abe67a 100644 --- a/crates/oapi/docs/derive_to_schema.md +++ b/crates/oapi/docs/derive_to_schema.md @@ -213,7 +213,7 @@ enum representation](https://serde.rs/enum-representations.html#untagged). Other _`serde`_ attributes works as is but does not have any effect on the generated OpenAPI doc. -**Note!** `tag` attribute has some limitations like it cannot be used +**Note**: `tag` attribute has some limitations like it cannot be used with **unnamed field structs** and **tuple types**. See more at [enum representation docs](https://serde.rs/enum-representations.html). diff --git a/crates/oapi/src/swagger_ui/config.rs b/crates/oapi/src/swagger_ui/config.rs index 8a01f5f0d..bd9fdbc72 100644 --- a/crates/oapi/src/swagger_ui/config.rs +++ b/crates/oapi/src/swagger_ui/config.rs @@ -657,7 +657,7 @@ impl<'a> Config<'a> { /// Set `with_credentials` to enable passing credentials to CORS requests send by browser as defined /// [fetch standards](https://fetch.spec.whatwg.org/#credentials). /// - /// **Note!** that Swagger UI cannot currently set cookies cross-domain + /// **Note**: that Swagger UI cannot currently set cookies cross-domain /// (see [swagger-js#1163](https://github.com/swagger-api/swagger-js/issues/1163)) - /// as a result, you will have to rely on browser-supplied cookies (which this setting enables sending) /// that Swagger UI cannot control.