docs: tweak scope docs

This commit is contained in:
Rob Ede 2024-06-07 22:30:43 +01:00
parent f367105c72
commit ea06965c4b
No known key found for this signature in database
GPG Key ID: 97C636207D3EF933
4 changed files with 31 additions and 20 deletions

View File

@ -198,28 +198,37 @@ method_macro!(Options, options);
method_macro!(Trace, trace); method_macro!(Trace, trace);
method_macro!(Patch, patch); method_macro!(Patch, patch);
/// Creates scope. /// Prepends a path prefix to all handlers using routing macros inside the attached module.
/// ///
/// Syntax: `#[scope("/path")]` /// # Syntax
/// ///
/// ## Attributes: /// ```
/// # use actix_web_codegen::scope;
/// #[scope("/prefix")]
/// mod api {
/// // ...
/// }
/// ```
/// ///
/// - `"/prefix"` - Raw literal string with path for which to register handler. Mandatory. /// # Arguments
///
/// - `"/prefix"` - Raw literal string to be prefixed onto contained handlers' paths.
/// ///
/// # Example /// # Example
/// ///
/// ``` /// ```
/// # use actix_web_codegen::scope; /// # use actix_web_codegen::{scope, get};
/// #[scope("/test")] /// # use actix_web::Responder;
/// mod scope_module { /// #[scope("/api")]
/// # use actix_web_codegen::get; /// mod api {
/// # use actix_web::{HttpResponse, Responder}; /// # use super::*;
/// #[get("/test")] /// #[get("/hello")]
/// pub async fn test() -> impl Responder { /// pub async fn hello() -> impl Responder {
/// // this has path /test/test /// // this has path /api/hello
/// HttpResponse::Ok().finish() /// "Hello, world!"
/// } /// }
/// } /// }
/// # fn main() {}
/// ``` /// ```
#[proc_macro_attribute] #[proc_macro_attribute]
pub fn scope(args: TokenStream, input: TokenStream) -> TokenStream { pub fn scope(args: TokenStream, input: TokenStream) -> TokenStream {

View File

@ -1,7 +1,6 @@
use proc_macro::TokenStream; use proc_macro::TokenStream;
use proc_macro2::{Span, TokenStream as TokenStream2}; use proc_macro2::{Span, TokenStream as TokenStream2};
use quote::quote; use quote::{quote, ToTokens as _};
use syn::LitStr;
use crate::{ use crate::{
input_and_compile_error, input_and_compile_error,
@ -17,7 +16,6 @@ pub fn with_scope(args: TokenStream, input: TokenStream) -> TokenStream {
fn with_scope_inner(args: TokenStream, input: TokenStream) -> syn::Result<TokenStream> { fn with_scope_inner(args: TokenStream, input: TokenStream) -> syn::Result<TokenStream> {
if args.is_empty() { if args.is_empty() {
// macro args are missing
return Err(syn::Error::new( return Err(syn::Error::new(
Span::call_site(), Span::call_site(),
"missing arguments for scope macro, \ "missing arguments for scope macro, \
@ -25,8 +23,7 @@ fn with_scope_inner(args: TokenStream, input: TokenStream) -> syn::Result<TokenS
)); ));
} }
let scope_prefix = syn::parse::<LitStr>(args.clone()).map_err(|err| { let scope_prefix = syn::parse::<syn::LitStr>(args.clone()).map_err(|err| {
// first macro arg is not a string literal
syn::Error::new( syn::Error::new(
err.span(), err.span(),
"argument to scope macro is not a string literal, \ "argument to scope macro is not a string literal, \
@ -40,7 +37,7 @@ fn with_scope_inner(args: TokenStream, input: TokenStream) -> syn::Result<TokenS
// modify any routing macros (method or route[s]) attached to // modify any routing macros (method or route[s]) attached to
// functions by prefixing them with this scope macro's argument // functions by prefixing them with this scope macro's argument
if let Some((_, ref mut items)) = module.content { if let Some((_, items)) = &mut module.content {
for item in items { for item in items {
if let syn::Item::Fn(fun) = item { if let syn::Item::Fn(fun) = item {
fun.attrs = fun fun.attrs = fun
@ -52,7 +49,7 @@ fn with_scope_inner(args: TokenStream, input: TokenStream) -> syn::Result<TokenS
} }
} }
Ok(TokenStream::from(quote! { #module })) Ok(module.to_token_stream().into())
} }
// Check if the attribute is a method type and has a route path, then modify it // Check if the attribute is a method type and has a route path, then modify it

View File

@ -9,6 +9,7 @@ pub fn image_guard(ctx: &GuardContext) -> bool {
#[scope("/test")] #[scope("/test")]
mod scope_module { mod scope_module {
// ensure that imports can be brought into the scope
use super::*; use super::*;
#[get("/test/guard", guard = "image_guard")] #[get("/test/guard", guard = "image_guard")]

View File

@ -32,6 +32,10 @@ all_crate_features := if os() == "linux" {
"--features='" + non_linux_all_features_list + "'" "--features='" + non_linux_all_features_list + "'"
} }
# Run Clippy over workspace.
clippy toolchain="":
cargo {{ toolchain }} clippy --workspace --all-targets {{ all_crate_features }}
# Test workspace using MSRV. # Test workspace using MSRV.
test-msrv: downgrade-for-msrv (test msrv_rustup) test-msrv: downgrade-for-msrv (test msrv_rustup)