feat: v6.0.3

Author: eastspire

src/common/enum.rs

@@ -2,16 +2,35 @@ use crate::*;
 
 /// Defines the type of macro handler.
 ///
-/// This enum is used to differentiate between simple macros and those that take attributes.
+/// This enum distinguishes between simple macros that do not accept attributes
+/// and more complex macros that can process attribute inputs. It is used to route
+/// macro invocations to the appropriate expansion logic based on their expected syntax.
 pub(crate) enum Handler {
-    /// A simple macro handler that takes no attributes.
+    /// A macro handler for simple macros that do not take any attributes.
+    ///
+    /// This variant is used for attribute-like macros that are invoked as `#[my_macro]`
+    /// without any additional arguments. The associated `MacroHandlerPosition` is responsible
+    /// for handling the macro at a specific location in the syntax tree.
     NoAttrPosition(MacroHandlerPosition),
-    /// A macro handler that takes attributes.
+    /// A macro handler for macros that accept attribute arguments.
+    ///
+    /// This variant is used for macros that support syntax like `#[my_macro(...)]`,
+    /// where the content inside the parentheses is parsed and processed as input.
+    /// The `MacroHandlerWithAttr` contains the logic to interpret and expand such macros.
     WithAttr(MacroHandlerWithAttr),
+    /// A macro handler for macros that accept attribute arguments and depend on position.
+    ///
+    /// This variant is used for macros with syntax like `#[my_macro(...)]`, similar to `WithAttr`.
+    /// The difference is that `WithAttrPosition` also incorporates the syntactic position
+    /// of the macro invocation into the expansion logic.
+    /// The `MacroHandlerWithAttrPosition` handles both the attribute input and the positional context.
     WithAttrPosition(MacroHandlerWithAttrPosition),
 }
 
+/// Defines the position where code should be injected in a function.
 pub(crate) enum Position {
+    /// Injects code at the beginning of the function body.
     Prologue,
+    /// Injects code at the end of the function body.
     Epilogue,
 }

src/common/fn.rs

@@ -69,6 +69,17 @@ fn inject_at_end(input: TokenStream, after_fn: impl FnOnce(&Ident) -> TokenStrea
     }
 }
 
+/// Injects code into a function at a specified position.
+///
+/// # Arguments
+///
+/// - `Position` - The position at which to inject the code (`Prologue` or `Epilogue`).
+/// - `TokenStream` - The input `TokenStream` of the function to modify.
+/// - `impl FnOnce(&Ident) -> TokenStream2` - A closure that generates the code to be injected, based on the function's context identifier.
+///
+/// # Returns
+///
+/// - `TokenStream` - Returns the modified `TokenStream` with the injected code.
 pub(crate) fn inject(
     position: Position,
     input: TokenStream,
@@ -88,7 +99,7 @@ pub(crate) fn inject(
 ///
 /// # Returns
 ///
-/// - `syn::Result<&Ident>` - The parsed context identifier or error.
+/// - `syn::Result<&Ident>` - Returns a `syn::Result` containing the context identifier if successful, or an error otherwise.
 pub(crate) fn parse_context_from_fn(sig: &Signature) -> syn::Result<&Ident> {
     match sig.inputs.first() {
         Some(FnArg::Typed(pat_type)) => match &*pat_type.pat {
@@ -117,11 +128,13 @@ pub(crate) fn parse_context_from_fn(sig: &Signature) -> syn::Result<&Ident> {
 /// - Any other expression types will result in `None`.
 /// - If `opt_expr` is `None`, the result is also `None`.
 ///
-/// # Parameters
-/// - `opt_expr` - An optional reference to the expression to convert.
+/// # Arguments
+///
+/// - `&Option<Expr>` - An optional reference to the expression to convert.
 ///
 /// # Returns
-/// - A `TokenStream2` representing `Some(isize)` for supported literals, or `None` otherwise.
+///
+/// - `TokenStream` - A `TokenStream2` representing `Some(isize)` for supported literals, or `None` otherwise.
 pub(crate) fn expr_to_isize(opt_expr: &Option<Expr>) -> TokenStream2 {
     match opt_expr {
         Some(expr) => match expr {

src/common/type.rs

@@ -10,5 +10,9 @@ pub(crate) type MacroHandlerPosition = fn(TokenStream, Position) -> TokenStream;
 /// and returns a `TokenStream`.
 pub(crate) type MacroHandlerWithAttr = fn(TokenStream, TokenStream) -> TokenStream;
 
+/// A type alias for a macro handler function that accepts attributes and a position.
+///
+/// This handler takes two `TokenStream`s as input (one for attributes, one for the item),
+/// a `Position` enum, and returns a `TokenStream`.
 pub(crate) type MacroHandlerWithAttrPosition =
     fn(TokenStream, TokenStream, Position) -> TokenStream;

src/hook/fn.rs

@@ -7,16 +7,16 @@ use crate::*;
 ///
 /// # Arguments
 ///
-/// - `TokenStream` - The attribute token stream, which can optionally specify an `order`.
-/// - `TokenStream` - The input token stream representing the function to be registered as a hook.
+/// - `attr` - The attribute `TokenStream`, which can optionally specify an `order`.
+/// - `item` - The input `TokenStream` representing the function to be registered as a hook.
 ///
 /// # Note
 ///
 /// If an order parameter is not specified, the hook will have a higher priority than hooks with a specified order.
 ///
 /// # Returns
 ///
-/// - `TokenStream` - The expanded token stream with the hook registration.
+/// Returns the expanded `TokenStream` with the hook registration.
 pub(crate) fn connected_hook_macro(attr: TokenStream, item: TokenStream) -> TokenStream {
     let attr_args: OrderAttr = parse_macro_input!(attr as OrderAttr);
     let order: TokenStream2 = expr_to_isize(&attr_args.order);
@@ -48,16 +48,16 @@ inventory::submit! {
 ///
 /// # Arguments
 ///
-/// - `TokenStream` - The attribute token stream, which can optionally specify an `order`.
-/// - `TokenStream` - The input token stream representing the function to be registered as a hook.
+/// - `attr` - The attribute `TokenStream`, which can optionally specify an `order`.
+/// - `item` - The input `TokenStream` representing the function to be registered as a hook.
 ///
 /// # Note
 ///
 /// If an order parameter is not specified, the hook will have a higher priority than hooks with a specified order.
 ///
 /// # Returns
 ///
-/// - `TokenStream` - The expanded token stream with the hook registration.
+/// Returns the expanded `TokenStream` with the hook registration.
 pub(crate) fn prologue_upgrade_hook_macro(attr: TokenStream, item: TokenStream) -> TokenStream {
     let attr_args: OrderAttr = parse_macro_input!(attr as OrderAttr);
     let order: TokenStream2 = expr_to_isize(&attr_args.order);
@@ -89,16 +89,16 @@ inventory::submit! {
 ///
 /// # Arguments
 ///
-/// - `TokenStream` - The attribute token stream, which can optionally specify an `order`.
-/// - `TokenStream` - The input token stream representing the function to be registered as a hook.
+/// - `attr` - The attribute `TokenStream`, which can optionally specify an `order`.
+/// - `item` - The input `TokenStream` representing the function to be registered as a hook.
 ///
 /// # Note
 ///
 /// If an order parameter is not specified, the hook will have a higher priority than hooks with a specified order.
 ///
 /// # Returns
 ///
-/// - `TokenStream` - The expanded token stream with the hook registration.
+/// Returns the expanded `TokenStream` with the hook registration.
 pub(crate) fn panic_hook_macro(attr: TokenStream, item: TokenStream) -> TokenStream {
     let attr_args: OrderAttr = parse_macro_input!(attr as OrderAttr);
     let order: TokenStream2 = expr_to_isize(&attr_args.order);
@@ -130,12 +130,12 @@ inventory::submit! {
 ///
 /// # Arguments
 ///
-/// - `TokenStream` - The attribute token stream, containing the path to disable the hook for and an optional order.
-/// - `TokenStream` - The input token stream representing the function to be registered.
+/// - `attr` - The attribute `TokenStream`, containing the path to disable the hook for and an optional order.
+/// - `item` - The input `TokenStream` representing the function to be registered.
 ///
 /// # Returns
 ///
-/// - `TokenStream` - The expanded token stream with the hook disabling registration.
+/// Returns the expanded `TokenStream` with the hook disabling registration.
 pub(crate) fn disable_http_hook_macro(attr: TokenStream, item: TokenStream) -> TokenStream {
     let attr_args: PathAttr = parse_macro_input!(attr as PathAttr);
     let path: &Expr = &attr_args.path;
@@ -167,12 +167,12 @@ inventory::submit! {
 ///
 /// # Arguments
 ///
-/// - `TokenStream` - The attribute token stream, containing the path to disable the hook for and an optional order.
-/// - `TokenStream` - The input token stream representing the function to be registered.
+/// - `attr` - The attribute `TokenStream`, containing the path to disable the hook for and an optional order.
+/// - `item` - The input `TokenStream` representing the function to be registered.
 ///
 /// # Returns
 ///
-/// - `TokenStream` - The expanded token stream with the hook disabling registration.
+/// Returns the expanded `TokenStream` with the hook disabling registration.
 pub(crate) fn disable_ws_hook_macro(attr: TokenStream, item: TokenStream) -> TokenStream {
     let attr_args: PathAttr = parse_macro_input!(attr as PathAttr);
     let path: &Expr = &attr_args.path;
@@ -201,12 +201,12 @@ inventory::submit! {
 ///
 /// # Arguments
 ///
-/// - `TokenStream` - The attribute token stream.
-/// - `TokenStream` - The input token stream to process.
+/// - `attr` - The attribute token stream.
+/// - `item` - The input token stream to process.
 ///
 /// # Returns
 ///
-/// - `TokenStream` - The expanded token stream with pre-hook call.
+/// Returns the expanded `TokenStream` with pre-hook call.
 pub(crate) fn prologue_hook_macro(
     attr: TokenStream,
     item: TokenStream,
@@ -231,12 +231,12 @@ inventory::submit! {
 ///
 /// # Arguments
 ///
-/// - `TokenStream` - The attribute token stream.
-/// - `TokenStream` - The input token stream to process.
+/// - `attr` - The attribute token stream.
+/// - `item` - The input token stream to process.
 ///
 /// # Returns
 ///
-/// - `TokenStream` - The expanded token stream with post-hook call.
+/// Returns the expanded `TokenStream` with post-hook call.
 pub(crate) fn epilogue_hook_macro(
     attr: TokenStream,
     item: TokenStream,

src/http/fn.rs

@@ -7,8 +7,12 @@ use crate::*;
 ///
 /// # Arguments
 ///
-/// - `$name`: The name of the generated handler function.
-/// - `$method`: The HTTP method as a string literal (e.g., "get", "post").
+/// - `$name` - The name of the generated handler function.
+/// - `$method` - The HTTP method as a string literal (e.g., "get", "post").
+///
+/// # Returns
+///
+/// Returns a macro that generates a handler function for the specified HTTP method.
 macro_rules! impl_http_method_macro {
     ($name:ident, $method:expr) => {
         pub(crate) fn $name(item: TokenStream, position: Position) -> TokenStream {
@@ -27,43 +31,43 @@ macro_rules! impl_http_method_macro {
     };
 }
 
-// This macro expands to a check that aborts the request if the HTTP method is not GET.
+// Generates a handler that checks if the HTTP method is GET.
 impl_http_method_macro!(get_handler, "get");
 
-// This macro expands to a check that aborts the request if the HTTP method is not POST.
+// Generates a handler that checks if the HTTP method is POST.
 impl_http_method_macro!(epilogue_handler, "post");
 
-// This macro expands to a check that aborts the request if the HTTP method is not PUT.
+// Generates a handler that checks if the HTTP method is PUT.
 impl_http_method_macro!(put_handler, "put");
 
-// This macro expands to a check that aborts the request if the HTTP method is not DELETE.
+// Generates a handler that checks if the HTTP method is DELETE.
 impl_http_method_macro!(delete_handler, "delete");
 
-// This macro expands to a check that aborts the request if the HTTP method is not PATCH.
+// Generates a handler that checks if the HTTP method is PATCH.
 impl_http_method_macro!(patch_handler, "patch");
 
-// This macro expands to a check that aborts the request if the HTTP method is not HEAD.
+// Generates a handler that checks if the HTTP method is HEAD.
 impl_http_method_macro!(head_handler, "head");
 
-// This macro expands to a check that aborts the request if the HTTP method is not OPTIONS.
+// Generates a handler that checks if the HTTP method is OPTIONS.
 impl_http_method_macro!(options_handler, "options");
 
-// This macro expands to a check that aborts the request if the HTTP method is not CONNECT.
+// Generates a handler that checks if the HTTP method is CONNECT.
 impl_http_method_macro!(connect_handler, "connect");
 
-// This macro expands to a check that aborts the request if the HTTP method is not TRACE.
+// Generates a handler that checks if the HTTP method is TRACE.
 impl_http_method_macro!(trace_handler, "trace");
 
-/// Creates method check function for HTTP request validation.
+/// Creates a method check function for HTTP request validation.
 ///
 /// # Arguments
 ///
-/// - `&str` - The method name string.
-/// - `proc_macro2::Span` - The span for error reporting.
+/// - `method_name` - The HTTP method name as a string.
+/// - `span` - The span for error reporting.
 ///
 /// # Returns
 ///
-/// - `impl FnOnce(&Ident) -> TokenStream2` - The generated check function.
+/// Returns a closure that generates the method check code.
 pub(crate) fn create_method_check(
     method_name: &str,
     span: proc_macro2::Span,
@@ -80,14 +84,18 @@ pub(crate) fn create_method_check(
 
 /// Handles HTTP requests for multiple method types.
 ///
+/// This macro allows a handler to respond to multiple HTTP methods.
+/// It generates code that checks if the request method matches any of the specified methods.
+///
 /// # Arguments
 ///
-/// - `TokenStream` - The attribute token stream.
-/// - `TokenStream` - The input token stream to process.
+/// - `attr` - The attribute `TokenStream` containing the list of allowed HTTP methods.
+/// - `item` - The input `TokenStream` representing the handler function.
+/// - `position` - The position at which to inject the method check code.
 ///
 /// # Returns
 ///
-/// - `TokenStream` - The expanded token stream with methods check.
+/// Returns the expanded `TokenStream` with the methods check code injected.
 pub(crate) fn methods_macro(
     attr: TokenStream,
     item: TokenStream,