improve doc

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<HttpResponse, actix_web::Error> {
-//!     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
+/// ### Attributes
-///
+/// - `"path"` - Raw literal string with path for which to register handler.
-/// - `"path"` - Raw literal string with path for which to register handler. Mandatory.
+/// - `method="HTTP_METHOD"` - Registers HTTP method to provide guard for. Upper-case string, "GET", "POST" for example.
-/// - `method="HTTP_METHOD"` - Registers HTTP method to provide guard for.
 /// - `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)*) => {
+    ($x:expr; $($tt:tt)*) => {
-        $(#[doc = $x])*
+        #[doc = $x]
         $($tt)*
     };
 }
 
 macro_rules! method_macro {
     (
-        $(
+        $($variant:ident, $method:ident,)+
-            ($method:ident, $variant:ident, $upper:ident);
-        )+
     ) => {
-        $(
+        $(doc_comment! {
-            doc_comment! {
+concat!("
-                concat!("Creates route handler with `", stringify!($upper), "` method guard.")
+Creates route handler with `actix_web::guard::", stringify!($variant), "`.
-                concat!("")
+
-                concat!("Syntax: `#[", stringify!($method), "(\"path\" [, attributes])]`")
+## Syntax
-                concat!("")
+
-                concat!("## Attributes:")
+    #[", stringify!($method), r#"("path"[, attributes])]
-                concat!("")
+
-                concat!("- `\"path\"` - *required* Raw literal string with path for which to register handler")
+### Attributes
-                concat!("- `guard = \"function_name\"` - Register function as guard using `actix_web::guard::fn_guard`")
+- `"path"` - Raw literal string with path for which to register handler.
-                concat!("- `wrap = \"Middleware\"` - Register a resource middleware.");
+- `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);
+    Get,       get,
-    (post,      Post,       POST);
+    Post,      post,
-    (put,       Put,        PUT);
+    Put,       put,
-    (delete,    Delete,     DELETE);
+    Delete,    delete,
-    (head,      Head,       HEAD);
+    Head,      head,
-    (connect,   Connect,    CONNECT);
+    Connect,   connect,
-    (options,   Options,    OPTIONS);
+    Options,   options,
-    (trace,     Trace,      TRACE);
+    Trace,     trace,
-    (patch,     Patch,      PATCH);
+    Patch,     patch,
 }
 
 /// Marks async main function as the actix system entry-point.

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);
+    Get,       GET,
-    (Post,      POST);
+    Post,      POST,
-    (Put,       PUT);
+    Put,       PUT,
-    (Delete,    DELETE);
+    Delete,    DELETE,
-    (Head,      HEAD);
+    Head,      HEAD,
-    (Connect,   CONNECT);
+    Connect,   CONNECT,
-    (Options,   OPTIONS);
+    Options,   OPTIONS,
-    (Trace,     TRACE);
+    Trace,     TRACE,
-    (Patch,     PATCH);
+    Patch,     PATCH,
 }
 
 impl ToTokens for MethodType {