From a9f497d05f259e91370b7c8ac5161adf958f5d13 Mon Sep 17 00:00:00 2001 From: Luca Palmieri Date: Fri, 28 Jan 2022 17:28:16 +0000 Subject: [PATCH 1/4] Guard against broken intra-doc links in CI (#2616) --- .github/workflows/clippy-fmt.yml | 18 ++++++++++++++++++ actix-files/src/named.rs | 3 ++- 2 files changed, 20 insertions(+), 1 deletion(-) diff --git a/.github/workflows/clippy-fmt.yml b/.github/workflows/clippy-fmt.yml index 9fcb0a561..9f5a0570a 100644 --- a/.github/workflows/clippy-fmt.yml +++ b/.github/workflows/clippy-fmt.yml @@ -5,6 +5,24 @@ on: types: [opened, synchronize, reopened] jobs: + lint-docs: + runs-on: ubuntu-latest + steps: + - uses: actions/checkout@v2 + - name: Install Rust + uses: actions-rs/toolchain@v1 + with: + toolchain: stable + profile: minimal + components: rust-docs + - name: Check for broken intra-doc links + uses: actions-rs/cargo@v1 + env: + RUSTDOCFLAGS: "-D warnings" + with: + command: doc + args: --no-deps --all-features --workspace + fmt: runs-on: ubuntu-latest steps: diff --git a/actix-files/src/named.rs b/actix-files/src/named.rs index 14495e660..cb6875065 100644 --- a/actix-files/src/named.rs +++ b/actix-files/src/named.rs @@ -209,6 +209,7 @@ impl NamedFile { Self::from_file(file, path) } + #[allow(rustdoc::broken_intra_doc_links)] /// Attempts to open a file asynchronously in read-only mode. /// /// When the `experimental-io-uring` crate feature is enabled, this will be async. @@ -300,7 +301,7 @@ impl NamedFile { /// Set content encoding for serving this file /// - /// Must be used with [`actix_web::middleware::Compress`] to take effect. + /// Must be used with `actix_web::middleware::Compress` to take effect. #[inline] pub fn set_content_encoding(mut self, enc: ContentEncoding) -> Self { self.encoding = Some(enc); From 21a08ca7969e9a08035a4b9e78d8419f3cce3c64 Mon Sep 17 00:00:00 2001 From: Rob Ede Date: Fri, 28 Jan 2022 20:27:16 +0000 Subject: [PATCH 2/4] tweak set_content_encoding docs --- .github/workflows/clippy-fmt.yml | 36 ++++++++++++++++---------------- actix-files/src/named.rs | 6 ++++-- 2 files changed, 22 insertions(+), 20 deletions(-) diff --git a/.github/workflows/clippy-fmt.yml b/.github/workflows/clippy-fmt.yml index 9f5a0570a..bc2cec145 100644 --- a/.github/workflows/clippy-fmt.yml +++ b/.github/workflows/clippy-fmt.yml @@ -5,24 +5,6 @@ on: types: [opened, synchronize, reopened] jobs: - lint-docs: - runs-on: ubuntu-latest - steps: - - uses: actions/checkout@v2 - - name: Install Rust - uses: actions-rs/toolchain@v1 - with: - toolchain: stable - profile: minimal - components: rust-docs - - name: Check for broken intra-doc links - uses: actions-rs/cargo@v1 - env: - RUSTDOCFLAGS: "-D warnings" - with: - command: doc - args: --no-deps --all-features --workspace - fmt: runs-on: ubuntu-latest steps: @@ -64,3 +46,21 @@ jobs: with: token: ${{ secrets.GITHUB_TOKEN }} args: --workspace --tests --examples --all-features + + lint-docs: + runs-on: ubuntu-latest + steps: + - uses: actions/checkout@v2 + - name: Install Rust + uses: actions-rs/toolchain@v1 + with: + toolchain: stable + profile: minimal + components: rust-docs + - name: Check for broken intra-doc links + uses: actions-rs/cargo@v1 + env: + RUSTDOCFLAGS: "-D warnings" + with: + command: doc + args: --no-deps --all-features --workspace diff --git a/actix-files/src/named.rs b/actix-files/src/named.rs index cb6875065..baf9b5531 100644 --- a/actix-files/src/named.rs +++ b/actix-files/src/named.rs @@ -299,9 +299,11 @@ impl NamedFile { self } - /// Set content encoding for serving this file + /// Sets content encoding for this file. /// - /// Must be used with `actix_web::middleware::Compress` to take effect. + /// This prevents the `Compress` middleware from modifying the file contents and signals to + /// browsers/clients how to decode it. For example, if serving a compressed HTML file (e.g., + /// `index.html.gz`) then use `.set_content_encoding(ContentEncoding::Gzip)`. #[inline] pub fn set_content_encoding(mut self, enc: ContentEncoding) -> Self { self.encoding = Some(enc); From a3416112a5010b378dcfaebad3b9c65f8838941e Mon Sep 17 00:00:00 2001 From: Luca Palmieri Date: Fri, 28 Jan 2022 20:31:54 +0000 Subject: [PATCH 3/4] Improve the documentation for `default_service` (#2614) --- src/app.rs | 17 ++--------------- src/resource.rs | 8 +++++--- src/scope.rs | 3 ++- 3 files changed, 9 insertions(+), 19 deletions(-) diff --git a/src/app.rs b/src/app.rs index da33ebc4b..bbf752595 100644 --- a/src/app.rs +++ b/src/app.rs @@ -236,9 +236,9 @@ where self } - /// Default service to be used if no matching resource could be found. + /// Default service that is invoked when no matching resource could be found. /// - /// It is possible to use services like `Resource`, `Route`. + /// You must use a [`Route`] as default service: /// /// ``` /// use actix_web::{web, App, HttpResponse}; @@ -253,19 +253,6 @@ where /// .default_service( /// web::route().to(|| HttpResponse::NotFound())); /// ``` - /// - /// It is also possible to use static files as default service. - /// - /// ``` - /// use actix_web::{web, App, HttpResponse}; - /// - /// let app = App::new() - /// .service( - /// web::resource("/index.html").to(|| HttpResponse::Ok())) - /// .default_service( - /// web::to(|| HttpResponse::NotFound()) - /// ); - /// ``` pub fn default_service(mut self, svc: F) -> Self where F: IntoServiceFactory, diff --git a/src/resource.rs b/src/resource.rs index a0fc19faf..3451eff45 100644 --- a/src/resource.rs +++ b/src/resource.rs @@ -312,9 +312,11 @@ where } } - /// Default service to be used if no matching route could be found. - /// By default *405* response get returned. Resource does not use - /// default handler from `App` or `Scope`. + /// Default service to be used if no matching route could be found. + /// You can pass a [`Route`] as default_service. + /// + /// If no default service is specified, a `405 Method Not Allowed` response will be returned to the caller. + /// [`Resource`] does **not** inherit the default handler specified on the parent [`App`](crate::App) or [`Scope`](crate::Scope). pub fn default_service(mut self, f: F) -> Self where F: IntoServiceFactory, diff --git a/src/scope.rs b/src/scope.rs index c05ce054d..0bad5c581 100644 --- a/src/scope.rs +++ b/src/scope.rs @@ -264,7 +264,8 @@ where /// Default service to be used if no matching route could be found. /// - /// If default resource is not registered, app's default resource is being used. + /// If a default service is not registered, it will fall back to the default service of + /// the parent [`App`](crate::App) (see [`App::default_service`](crate::App::default_service). pub fn default_service(mut self, f: F) -> Self where F: IntoServiceFactory, From b3e84b5c4bf32fd8aeac8c938f9906ce730a7458 Mon Sep 17 00:00:00 2001 From: Rob Ede Date: Fri, 28 Jan 2022 20:53:51 +0000 Subject: [PATCH 4/4] tweak default_service docs --- src/app.rs | 12 +++++++----- src/app_service.rs | 2 +- src/resource.rs | 10 ++++++---- src/scope.rs | 4 ++-- 4 files changed, 16 insertions(+), 12 deletions(-) diff --git a/src/app.rs b/src/app.rs index bbf752595..a63cf5d50 100644 --- a/src/app.rs +++ b/src/app.rs @@ -238,8 +238,12 @@ where /// Default service that is invoked when no matching resource could be found. /// - /// You must use a [`Route`] as default service: + /// You can use a [`Route`] as default service. /// + /// If a default service is not registered, an empty `404 Not Found` response will be sent to + /// the client instead. + /// + /// # Examples /// ``` /// use actix_web::{web, App, HttpResponse}; /// @@ -248,10 +252,8 @@ where /// } /// /// let app = App::new() - /// .service( - /// web::resource("/index.html").route(web::get().to(index))) - /// .default_service( - /// web::route().to(|| HttpResponse::NotFound())); + /// .service(web::resource("/index.html").route(web::get().to(index))) + /// .default_service(web::to(|| HttpResponse::NotFound())); /// ``` pub fn default_service(mut self, svc: F) -> Self where diff --git a/src/app_service.rs b/src/app_service.rs index edfb3e4a2..dbd718330 100644 --- a/src/app_service.rs +++ b/src/app_service.rs @@ -72,7 +72,7 @@ where }))) }); - // App config + // create App config to pass to child services let mut config = AppService::new(config, default.clone()); // register services diff --git a/src/resource.rs b/src/resource.rs index 3451eff45..6a01a0496 100644 --- a/src/resource.rs +++ b/src/resource.rs @@ -312,11 +312,13 @@ where } } - /// Default service to be used if no matching route could be found. - /// You can pass a [`Route`] as default_service. + /// Default service to be used if no matching route could be found. /// - /// If no default service is specified, a `405 Method Not Allowed` response will be returned to the caller. - /// [`Resource`] does **not** inherit the default handler specified on the parent [`App`](crate::App) or [`Scope`](crate::Scope). + /// You can use a [`Route`] as default service. + /// + /// If a default service is not registered, an empty `405 Method Not Allowed` response will be + /// sent to the client instead. Unlike [`Scope`](crate::Scope)s, a [`Resource`] does **not** + /// inherit its parent's default service. pub fn default_service(mut self, f: F) -> Self where F: IntoServiceFactory, diff --git a/src/scope.rs b/src/scope.rs index 0bad5c581..dad727430 100644 --- a/src/scope.rs +++ b/src/scope.rs @@ -262,10 +262,10 @@ where ) } - /// Default service to be used if no matching route could be found. + /// Default service to be used if no matching resource could be found. /// /// If a default service is not registered, it will fall back to the default service of - /// the parent [`App`](crate::App) (see [`App::default_service`](crate::App::default_service). + /// the parent [`App`](crate::App) (see [`App::default_service`](crate::App::default_service)). pub fn default_service(mut self, f: F) -> Self where F: IntoServiceFactory,