From 60d21e68d8532514caab16758fcfaab857e37e04 Mon Sep 17 00:00:00 2001 From: Arniu Date: Tue, 22 Sep 2020 22:01:57 +0800 Subject: [PATCH] improve doc --- actix-web-codegen/src/lib.rs | 149 +++++++++++++++------------------ actix-web-codegen/src/route.rs | 22 +++-- 2 files changed, 78 insertions(+), 93 deletions(-) diff --git a/actix-web-codegen/src/lib.rs b/actix-web-codegen/src/lib.rs index ff6f82dfd..8d9a36b4a 100644 --- a/actix-web-codegen/src/lib.rs +++ b/actix-web-codegen/src/lib.rs @@ -1,114 +1,101 @@ #![recursion_limit = "512"] -//! Helper and convenience macros for Actix-web. -//! -//! ## Runtime Setup -//! -//! - [main](attr.main.html) -//! -//! ## Resource Macros: -//! -//! - [get](attr.get.html) -//! - [post](attr.post.html) -//! - [put](attr.put.html) -//! - [delete](attr.delete.html) -//! - [head](attr.head.html) -//! - [connect](attr.connect.html) -//! - [options](attr.options.html) -//! - [trace](attr.trace.html) -//! - [patch](attr.patch.html) -//! - [route](attr.route.html) -//! -//! ### Attributes: -//! -//! - `"path"` - *Required*, raw literal string with path for which to register handle -//! - `method="HTTP_METHOD"` - Secondary HTTP method accepted, uppercased string. "GET", "POST" for example -//! - `guard="function_name"` - Registers function as guard using `actix_web::guard::fn_guard` -//! - `wrap="Middleware"` - Registers a resource middleware. -//! -//! ### Notes -//! -//! Function name can be specified as any expression that is going to be accessible to the generate -//! code (e.g `my_guard` or `my_module::my_guard`) -//! -//! ### Example: -//! -//! ```rust -//! use actix_web::HttpResponse; -//! use actix_web_codegen::get; -//! -//! #[get("/test")] -//! async fn async_test() -> Result { -//! Ok(HttpResponse::Ok().finish()) -//! } -//! ``` - extern crate proc_macro; -mod route; - use proc_macro::TokenStream; +mod route; + /// Creates resource handler, allowing multiple HTTP method guards. /// -/// Syntax: `#[route("path"[, attributes])]` +/// ## Syntax /// -/// Example: `#[route("/", method="GET", method="HEAD")]` +/// #[route("path", method="HTTP_METHOD"[, attributes])] /// -/// ## Attributes -/// -/// - `"path"` - Raw literal string with path for which to register handler. Mandatory. -/// - `method="HTTP_METHOD"` - Registers HTTP method to provide guard for. +/// ### Attributes +/// - `"path"` - Raw literal string with path for which to register handler. +/// - `method="HTTP_METHOD"` - Registers HTTP method to provide guard for. Upper-case string, "GET", "POST" for example. /// - `guard="function_name"` - Registers function as guard using `actix_web::guard::fn_guard` /// - `wrap="Middleware"` - Registers a resource middleware. +/// +/// ### Notes +/// Function name can be specified as any expression that is going to be accessible to the generate +/// code, e.g `my_guard` or `my_module::my_guard`. +/// +/// ## Example +/// +/// ```rust +/// use actix_web::HttpResponse; +/// use actix_web_codegen::route; +/// +/// #[route("/", method="GET", method="HEAD")] +/// fn async example() -> HttpResponse { +/// Ok(HttpResponse::Ok().finish()) +/// } +/// ``` #[proc_macro_attribute] pub fn route(args: TokenStream, input: TokenStream) -> TokenStream { route::with_method(None, args, input) } macro_rules! doc_comment { - ($($x:expr)*; $($tt:tt)*) => { - $(#[doc = $x])* + ($x:expr; $($tt:tt)*) => { + #[doc = $x] $($tt)* }; } macro_rules! method_macro { ( - $( - ($method:ident, $variant:ident, $upper:ident); - )+ + $($variant:ident, $method:ident,)+ ) => { - $( - doc_comment! { - concat!("Creates route handler with `", stringify!($upper), "` method guard.") - concat!("") - concat!("Syntax: `#[", stringify!($method), "(\"path\" [, attributes])]`") - concat!("") - concat!("## Attributes:") - concat!("") - concat!("- `\"path\"` - *required* Raw literal string with path for which to register handler") - concat!("- `guard = \"function_name\"` - Register function as guard using `actix_web::guard::fn_guard`") - concat!("- `wrap = \"Middleware\"` - Register a resource middleware."); - #[proc_macro_attribute] - pub fn $method(args: TokenStream, input: TokenStream) -> TokenStream { - route::with_method(Some(route::MethodType::$variant), args, input) - } + $(doc_comment! { +concat!(" +Creates route handler with `actix_web::guard::", stringify!($variant), "`. + +## Syntax + + #[", stringify!($method), r#"("path"[, attributes])] + +### Attributes +- `"path"` - Raw literal string with path for which to register handler. +- `guard="function_name"` - Registers function as guard using `actix_web::guard::fn_guard`. +- `wrap="Middleware"` - Registers a resource middleware. + +### Notes +Function name can be specified as any expression that is going to be accessible to the generate +code, e.g `my_guard` or `my_module::my_guard`. + +## Example + +```rust +use actix_web::HttpResponse; +use actix_web_codegen::"#, stringify!($method), "; + +#[", stringify!($method), r#"("/")] +fn async example() -> HttpResponse { + Ok(HttpResponse::Ok().finish()) +} +``` +"#); + #[proc_macro_attribute] + pub fn $method(args: TokenStream, input: TokenStream) -> TokenStream { + route::with_method(Some(route::MethodType::$variant), args, input) } - )+ + })+ }; } method_macro! { - (get, Get, GET); - (post, Post, POST); - (put, Put, PUT); - (delete, Delete, DELETE); - (head, Head, HEAD); - (connect, Connect, CONNECT); - (options, Options, OPTIONS); - (trace, Trace, TRACE); - (patch, Patch, PATCH); + Get, get, + Post, post, + Put, put, + Delete, delete, + Head, head, + Connect, connect, + Options, options, + Trace, trace, + Patch, patch, } /// Marks async main function as the actix system entry-point. diff --git a/actix-web-codegen/src/route.rs b/actix-web-codegen/src/route.rs index 8670cc0dc..9f99ff01a 100644 --- a/actix-web-codegen/src/route.rs +++ b/actix-web-codegen/src/route.rs @@ -22,9 +22,7 @@ impl ToTokens for ResourceType { macro_rules! method_type { ( - $( - ($variant:ident, $upper:ident); - )+ + $($variant:ident, $upper:ident,)+ ) => { #[derive(Debug, PartialEq, Eq, Hash)] pub enum MethodType { @@ -51,15 +49,15 @@ macro_rules! method_type { } method_type! { - (Get, GET); - (Post, POST); - (Put, PUT); - (Delete, DELETE); - (Head, HEAD); - (Connect, CONNECT); - (Options, OPTIONS); - (Trace, TRACE); - (Patch, PATCH); + Get, GET, + Post, POST, + Put, PUT, + Delete, DELETE, + Head, HEAD, + Connect, CONNECT, + Options, OPTIONS, + Trace, TRACE, + Patch, PATCH, } impl ToTokens for MethodType {