diff --git a/compiler/rustc_macros/src/lib.rs b/compiler/rustc_macros/src/lib.rs
index 619f93c8a533a..14e6a06839e13 100644
--- a/compiler/rustc_macros/src/lib.rs
+++ b/compiler/rustc_macros/src/lib.rs
@@ -41,6 +41,20 @@ pub fn symbols(input: TokenStream) -> TokenStream {
     symbols::symbols(input.into()).into()
 }
 
+/// Derive an extension trait for a given impl block. The trait name
+/// goes into the parenthesized args of the macro, for greppability.
+/// For example:
+/// ```
+/// use rustc_macros::extension;
+/// #[extension(pub trait Foo)]
+/// impl i32 { fn hello() {} }
+/// ```
+///
+/// expands to:
+/// ```
+/// pub trait Foo { fn hello(); }
+/// impl Foo for i32 { fn hello() {} }
+/// ```
 #[proc_macro_attribute]
 pub fn extension(attr: TokenStream, input: TokenStream) -> TokenStream {
     extension::extension(attr, input)