diff --git a/tokio-macros/src/lib.rs b/tokio-macros/src/lib.rs
index fb7036c3a34..3f17d52a98e 100644
--- a/tokio-macros/src/lib.rs
+++ b/tokio-macros/src/lib.rs
@@ -187,6 +187,8 @@ use proc_macro::TokenStream;
 pub fn main(args: TokenStream, item: TokenStream) -> TokenStream {
     entry::main(args, item.clone(), true).unwrap_or_else(|err| {
         let mut output: TokenStream = err.to_compile_error().into();
+        // Append the item in case of errors so that IDEs can still properly resolve the annotated
+        // item in the attribute expansion in case of failure
         output.extend(item);
         output
     })
@@ -237,6 +239,8 @@ pub fn main(args: TokenStream, item: TokenStream) -> TokenStream {
 pub fn main_rt(args: TokenStream, item: TokenStream) -> TokenStream {
     entry::main(args, item.clone(), false).unwrap_or_else(|err| {
         let mut output: TokenStream = err.to_compile_error().into();
+        // Append the item in case of errors so that IDEs can still properly resolve the annotated
+        // item in the attribute expansion in case of failure
         output.extend(item);
         output
     })
@@ -287,6 +291,8 @@ pub fn main_rt(args: TokenStream, item: TokenStream) -> TokenStream {
 pub fn test(args: TokenStream, item: TokenStream) -> TokenStream {
     entry::test(args, item.clone(), true).unwrap_or_else(|err| {
         let mut output: TokenStream = err.to_compile_error().into();
+        // Append the item in case of errors so that IDEs can still properly resolve the annotated
+        // item in the attribute expansion in case of failure
         output.extend(item);
         output
     })
@@ -313,6 +319,8 @@ pub fn test(args: TokenStream, item: TokenStream) -> TokenStream {
 pub fn test_rt(args: TokenStream, item: TokenStream) -> TokenStream {
     entry::test(args, item.clone(), false).unwrap_or_else(|err| {
         let mut output: TokenStream = err.to_compile_error().into();
+        // Append the item in case of errors so that IDEs can still properly resolve the annotated
+        // item in the attribute expansion in case of failure
         output.extend(item);
         output
     })