Introdcue #[rune::macro_] and capture documentation for macros

book/src/macros.md

@@ -39,7 +39,7 @@ A macro is added to a [`Module`] using the [`Module::macro_`] function.
 ```rust,noplaypen
 pub fn module() -> Result<rune::Module, rune::ContextError> {
     let mut module = rune::Module::new(["std", "experiments"]);
-    module.macro_(["stringy_math"], stringy_math_macro::stringy_math)?;
+    module.macro_meta(stringy_math_macro::stringy_math)?;
     Ok(module)
 }
 ```

crates/rune-macros/src/function.rs

@@ -50,14 +50,18 @@ impl FunctionAttrs {
 
                 out.path = Path::Path(span, self_type, parse_path(input, head)?);
             } else {
-                return Err(syn::Error::new_spanned(ident, "unsupported option"));
+                return Err(syn::Error::new_spanned(ident, "Unsupported option"));
             }
 
-            if !input.peek(syn::Token![,]) {
+            if input.parse::<Option<syn::Token![,]>>()?.is_none() {
                 break;
             }
+        }
+
+        let stream = input.parse::<TokenStream>()?;
 
-            input.parse::<syn::Token![,]>()?;
+        if !stream.is_empty() {
+            return Err(syn::Error::new_spanned(stream, "Unexpected input"));
         }
 
         Ok(out)
@@ -298,9 +302,9 @@ impl Function {
         stream.extend(quote! {
             /// Get function metadata.
             #[automatically_derived]
-            #meta_vis fn #meta_fn() -> rune::compile::FunctionMetaData {
-                rune::compile::FunctionMetaData {
-                    kind: rune::compile::FunctionMetaKind::#meta_kind(#meta_name, #real_fn_path),
+            #meta_vis fn #meta_fn() -> rune::__private::FunctionMetaData {
+                rune::__private::FunctionMetaData {
+                    kind: rune::__private::FunctionMetaKind::#meta_kind(#meta_name, #real_fn_path),
                     name: #name_string,
                     docs: &#docs[..],
                     arguments: &#arguments[..],

crates/rune-macros/src/lib.rs

@@ -30,6 +30,7 @@ mod from_value;
 mod function;
 mod instrument;
 mod internals;
+mod macro_;
 mod opaque;
 mod option_spanned;
 mod parse;
@@ -194,6 +195,22 @@ pub fn function(
     output.into()
 }
 
+#[proc_macro_attribute]
+pub fn macro_(
+    attrs: proc_macro::TokenStream,
+    item: proc_macro::TokenStream,
+) -> proc_macro::TokenStream {
+    let attrs = syn::parse_macro_input!(attrs with crate::macro_::Config::parse);
+    let macro_ = syn::parse_macro_input!(item with crate::macro_::Macro::parse);
+
+    let output = match macro_.expand(attrs) {
+        Ok(output) => output,
+        Err(e) => return proc_macro::TokenStream::from(e.to_compile_error()),
+    };
+
+    output.into()
+}
+
 /// Helper derive to implement `ToTokens`.
 #[proc_macro_derive(ToTokens, attributes(rune))]
 #[doc(hidden)]

crates/rune-macros/src/macro_.rs

@@ -0,0 +1,193 @@
+use proc_macro2::{Span, TokenStream};
+use quote::{quote, ToTokens};
+use syn::parse::ParseStream;
+use syn::punctuated::Punctuated;
+use syn::spanned::Spanned;
+use syn::Error;
+
+#[derive(Default)]
+enum Path {
+    #[default]
+    None,
+    Path(Span, syn::Path),
+}
+
+#[derive(Default)]
+pub(crate) struct Config {
+    path: Path,
+}
+
+impl Config {
+    /// Parse the given parse stream.
+    pub(crate) fn parse(input: ParseStream) -> Result<Self, Error> {
+        let span = input.span();
+        let mut out = Self::default();
+
+        while !input.is_empty() {
+            let ident = input.parse::<syn::Ident>()?;
+
+            if ident == "path" {
+                input.parse::<syn::Token![=]>()?;
+                out.path = Path::Path(span, input.parse()?);
+            } else {
+                return Err(syn::Error::new_spanned(ident, "Unsupported option"));
+            }
+
+            if input.parse::<Option<syn::Token![,]>>()?.is_none() {
+                break;
+            }
+        }
+
+        let stream = input.parse::<TokenStream>()?;
+
+        if !stream.is_empty() {
+            return Err(syn::Error::new_spanned(stream, "Unexpected input"));
+        }
+
+        Ok(out)
+    }
+}
+
+pub(crate) struct Macro {
+    attributes: Vec<syn::Attribute>,
+    vis: syn::Visibility,
+    sig: syn::Signature,
+    remainder: TokenStream,
+    name_string: syn::LitStr,
+    docs: syn::ExprArray,
+    meta_vis: syn::Visibility,
+    real_fn: syn::Ident,
+    meta_fn: syn::Ident,
+}
+
+impl Macro {
+    /// Parse the given parse stream.
+    pub(crate) fn parse(input: ParseStream) -> Result<Self, Error> {
+        let parsed_attributes = input.call(syn::Attribute::parse_outer)?;
+        let vis = input.parse::<syn::Visibility>()?;
+        let mut sig = input.parse::<syn::Signature>()?;
+        let ident = sig.ident.clone();
+
+        let mut attributes = Vec::new();
+
+        let mut docs = syn::ExprArray {
+            attrs: Vec::new(),
+            bracket_token: syn::token::Bracket::default(),
+            elems: Punctuated::default(),
+        };
+
+        for attr in parsed_attributes {
+            if attr.path().is_ident("doc") {
+                if let syn::Meta::NameValue(name_value) = &attr.meta {
+                    docs.elems.push(name_value.value.clone());
+                }
+            }
+
+            attributes.push(attr);
+        }
+
+        let name_string = syn::LitStr::new(&ident.to_string(), ident.span());
+
+        let meta_vis = vis.clone();
+        let meta_fn = sig.ident.clone();
+        let real_fn = syn::Ident::new(&format!("__rune_macro__{}", sig.ident), sig.ident.span());
+        sig.ident = real_fn.clone();
+
+        let remainder = input.parse::<TokenStream>()?;
+
+        Ok(Self {
+            attributes,
+            vis,
+            sig,
+            remainder,
+            name_string,
+            docs,
+            meta_vis,
+            real_fn,
+            meta_fn,
+        })
+    }
+
+    /// Expand the function declaration.
+    pub(crate) fn expand(self, attrs: Config) -> Result<TokenStream, Error> {
+        let real_fn_path = {
+            let mut segments = Punctuated::default();
+
+            segments.push(syn::PathSegment {
+                ident: self.real_fn,
+                arguments: syn::PathArguments::None,
+            });
+
+            syn::TypePath {
+                qself: None,
+                path: syn::Path {
+                    leading_colon: None,
+                    segments,
+                },
+            }
+        };
+
+        let meta_name = syn::Expr::Array({
+            let mut meta_name = syn::ExprArray {
+                attrs: Vec::new(),
+                bracket_token: syn::token::Bracket::default(),
+                elems: Punctuated::default(),
+            };
+
+            match attrs.path {
+                Path::None => {
+                    meta_name.elems.push(syn::Expr::Lit(syn::ExprLit {
+                        attrs: Vec::new(),
+                        lit: syn::Lit::Str(self.name_string.clone()),
+                    }));
+                }
+                Path::Path(_, path) => {
+                    for s in &path.segments {
+                        let syn::PathArguments::None = s.arguments else {
+                            return Err(syn::Error::new_spanned(s, "Expected simple ident path segment"));
+                        };
+
+                        let ident = syn::LitStr::new(&s.ident.to_string(), s.span());
+
+                        meta_name.elems.push(syn::Expr::Lit(syn::ExprLit {
+                            attrs: Vec::new(),
+                            lit: syn::Lit::Str(ident),
+                        }));
+                    }
+                }
+            }
+
+            meta_name
+        });
+
+        let mut stream = TokenStream::new();
+
+        for attr in self.attributes {
+            stream.extend(attr.into_token_stream());
+        }
+
+        stream.extend(quote!(#[allow(non_snake_case)]));
+        stream.extend(self.vis.into_token_stream());
+        stream.extend(self.sig.into_token_stream());
+        stream.extend(self.remainder);
+
+        let meta_vis = &self.meta_vis;
+        let meta_fn = &self.meta_fn;
+        let docs = &self.docs;
+        let name_string = self.name_string;
+
+        stream.extend(quote! {
+            /// Get function metadata.
+            #[automatically_derived]
+            #meta_vis fn #meta_fn() -> rune::__private::MacroMetaData {
+                rune::__private::MacroMetaData {
+                    kind: rune::__private::MacroMetaKind::function(#meta_name, #real_fn_path),
+                    name: #name_string,
+                    docs: &#docs[..],
+                }
+            }
+        });
+
+        Ok(stream)
+    }
+}

crates/rune-modules/src/experiments.rs

@@ -30,21 +30,20 @@ mod stringy_math_macro;
 /// Construct the `std::experiments` module, which contains experiments.
 pub fn module(_stdio: bool) -> Result<Module, ContextError> {
     let mut module = Module::with_crate_item("std", ["experiments"]);
-    module.macro_(["passthrough"], passthrough_impl)?;
-    module.macro_(["stringy_math"], stringy_math_macro::stringy_math)?;
-    module.macro_(["make_function"], make_function)?;
+    module.macro_meta(passthrough)?;
+    module.macro_meta(stringy_math_macro::stringy_math)?;
+    module.macro_meta(make_function)?;
     Ok(module)
 }
 
 /// Implementation for the `passthrough!` macro.
-fn passthrough_impl(
-    _: &mut MacroContext<'_>,
-    stream: &TokenStream,
-) -> compile::Result<TokenStream> {
+#[rune::macro_]
+fn passthrough(_: &mut MacroContext<'_>, stream: &TokenStream) -> compile::Result<TokenStream> {
     Ok(stream.clone())
 }
 
 /// Implementation for the `make_function!` macro.
+#[rune::macro_]
 fn make_function(ctx: &mut MacroContext<'_>, stream: &TokenStream) -> compile::Result<TokenStream> {
     let mut parser = Parser::from_token_stream(stream, ctx.stream_span());
 

crates/rune-modules/src/experiments/stringy_math_macro.rs

@@ -4,6 +4,7 @@ use rune::macros::{quote, MacroContext, TokenStream};
 use rune::parse::Parser;
 
 /// Implementation for the `stringy_math!` macro.
+#[rune::macro_]
 pub(crate) fn stringy_math(
     ctx: &mut MacroContext<'_>,
     stream: &TokenStream,

crates/rune/src/ast.rs

@@ -14,6 +14,7 @@
 //! use rune::parse::Parser;
 //! use std::sync::Arc;
 //!
+//! #[rune::macro_]
 //! fn ident_to_string(ctx: &mut MacroContext<'_>, stream: &TokenStream) -> compile::Result<TokenStream> {
 //!     let mut p = Parser::from_token_stream(stream, ctx.stream_span());
 //!     let ident = p.parse_all::<ast::Ident>()?;
@@ -22,8 +23,9 @@
 //!     Ok(quote!(#string).into_token_stream(ctx))
 //! }
 //!
+//! # fn main() -> rune::Result<()> {
 //! let mut m = Module::new();
-//! m.macro_(["ident_to_string"], ident_to_string)?;
+//! m.macro_meta(ident_to_string)?;
 //!
 //! let mut context = Context::new();
 //! context.install(m)?;
@@ -49,7 +51,8 @@
 //! let value: String = rune::from_value(value)?;
 //!
 //! assert_eq!(value, "hello");
-//! # Ok::<_, rune::Error>(())
+//! # Ok(())
+//! # }
 //! ```
 
 use crate::macros::{MacroContext, ToTokens, TokenStream};