style(macro): cleanup from outer macro refactor

Refs: 335

Author: Xenira

crates/macros/src/constant.rs

@@ -1,5 +1,5 @@
 use crate::helpers::get_docs;
-use anyhow::{bail, Result};
+use anyhow::Result;
 use darling::ToTokens;
 use proc_macro2::TokenStream;
 use quote::quote;

crates/macros/src/function.rs

@@ -7,8 +7,8 @@ use darling::{FromMeta, ToTokens};
 use proc_macro2::{Ident, Literal, Span, TokenStream};
 use quote::quote;
 use syn::{
-    punctuated::Punctuated, AttributeArgs, FnArg, GenericArgument, ItemFn, Lit, PathArguments,
-    ReturnType, Signature, Token, Type, TypePath,
+    punctuated::Punctuated, FnArg, GenericArgument, ItemFn, Lit, PathArguments, ReturnType,
+    Signature, Token, Type, TypePath,
 };
 
 #[derive(Default, Debug, FromMeta)]

crates/macros/src/lib.rs

@@ -13,78 +13,37 @@ mod startup_function;
 mod syn_ext;
 mod zval;
 
-use std::collections::HashMap;
-
-use constant::Constant;
-use darling::FromMeta;
 use proc_macro::TokenStream;
-use proc_macro2::{Span, TokenStream as TokenStream2};
-use syn::{
-    parse_macro_input, AttributeArgs, DeriveInput, ItemConst, ItemFn, ItemForeignMod, ItemMod,
-    NestedMeta,
-};
+use proc_macro2::Span;
+use syn::{parse_macro_input, DeriveInput, ItemFn, ItemForeignMod, ItemMod};
 
 extern crate proc_macro;
 
-#[derive(Default, Debug)]
-struct State {
-    functions: Vec<function::Function>,
-    classes: HashMap<String, class::Class>,
-    constants: Vec<Constant>,
-}
-
-impl State {
-    fn parse_from_meta<T>(
-        meta: &Vec<NestedMeta>,
-        call_site: Option<Span>,
-    ) -> Result<T, TokenStream2>
-    where
-        T: FromMeta,
-    {
-        T::from_list(&meta).map_err(|e| {
-            syn::Error::new(
-                call_site.unwrap_or_else(Span::call_site),
-                format!("Unable to parse attribute arguments: {:?}", e),
-            )
-            .to_compile_error()
-            .into()
-        })
-    }
-}
-
+/// Structs can be exported to PHP as classes with the #[php_class] attribute macro. This attribute derives the RegisteredClass trait on your struct, as well as registering the class to be registered with the #[php_module] macro.
 #[proc_macro_attribute]
 pub fn php_class(_args: TokenStream, _input: TokenStream) -> TokenStream {
-    // let args = parse_macro_input!(args as AttributeArgs);
-    // let input = parse_macro_input!(input as ItemStruct);
-    //
-    // match class::parser(args, input) {
-    //     Ok((parsed, _)) => parsed,
-    //     Err(e) => syn::Error::new(Span::call_site(), e).to_compile_error(),
-    // }
-    // .into()
-    syn::Error::new(Span::call_site(), "php_class is not supported")
-        .to_compile_error()
-        .into()
+    syn::Error::new(
+        Span::call_site(),
+        "php_class can only be used inside a #[php_module] module",
+    )
+    .to_compile_error()
+    .into()
 }
 
+/// Used to annotate functions which should be exported to PHP. Note that this should not be used on class methods - see the #[php_impl] macro for that.
 #[proc_macro_attribute]
-pub fn php_function(args: TokenStream, input: TokenStream) -> TokenStream {
-    let args = parse_macro_input!(args as AttributeArgs);
-    let input = parse_macro_input!(input as ItemFn);
-    let attr_args = match State::parse_from_meta(&args, None) {
-        Ok(attr_args) => attr_args,
-        Err(e) => return e.into(),
-    };
-
-    match function::parser(attr_args, &input) {
-        Ok((parsed, _)) => parsed,
-        Err(e) => syn::Error::new(Span::call_site(), e).to_compile_error(),
-    }
+pub fn php_function(_args: TokenStream, _input: TokenStream) -> TokenStream {
+    syn::Error::new(
+        Span::call_site(),
+        "php_function can only be used inside a #[php_module] module",
+    )
+    .to_compile_error()
     .into()
 }
 
+/// The module macro is used to annotate the get_module function, which is used by the PHP interpreter to retrieve information about your extension, including the name, version, functions and extra initialization functions. Regardless if you use this macro, your extension requires a extern "C" fn get_module() so that PHP can get this information.
 #[proc_macro_attribute]
-pub fn php_module(_: TokenStream, input: TokenStream) -> TokenStream {
+pub fn php_module(_args: TokenStream, input: TokenStream) -> TokenStream {
     let input = parse_macro_input!(input as ItemMod);
 
     match module::parser(input) {
@@ -94,51 +53,47 @@ pub fn php_module(_: TokenStream, input: TokenStream) -> TokenStream {
     .into()
 }
 
+/// Used to define the PHP extension startup function. This function is used to register extension classes and constants with the PHP interpreter.
 #[proc_macro_attribute]
-pub fn php_startup(args: TokenStream, input: TokenStream) -> TokenStream {
-    // let args = parse_macro_input!(args as AttributeArgs);
-    // let input = parse_macro_input!(input as ItemFn);
-    // let attr_args = match State::parse_from_meta(&args, None) {
-    //     Ok(attr_args) => attr_args,
-    //     Err(e) => return e.into(),
-    // };
-    //
-    // match startup_function::parser(Some(attr_args), &input) {
-    //     Ok((parsed, _)) => parsed,
-    //     Err(e) => syn::Error::new(Span::call_site(), e).to_compile_error(),
-    // }
-    // .into()
-    syn::Error::new(Span::call_site(), "php_startup is not supported")
-        .to_compile_error()
-        .into()
+pub fn php_startup(_args: TokenStream, _input: TokenStream) -> TokenStream {
+    syn::Error::new(
+        Span::call_site(),
+        "php_startup can only be used inside a #[php_module] module",
+    )
+    .to_compile_error()
+    .into()
 }
 
+/// You can export an entire impl block to PHP. This exports all methods as well as constants to PHP on the class that it is implemented on. This requires the #[php_class] macro to already be used on the underlying struct. Trait implementations cannot be exported to PHP.
 #[proc_macro_attribute]
-pub fn php_impl(args: TokenStream, input: TokenStream) -> TokenStream {
-    // let args = parse_macro_input!(args as AttributeArgs);
-    // let input = parse_macro_input!(input as ItemImpl);
-    //
-    // match impl_::parser(args, input) {
-    //     Ok(parsed) => parsed,
-    //     Err(e) => syn::Error::new(Span::call_site(), e).to_compile_error(),
-    // }
-    // .into()
-    syn::Error::new(Span::call_site(), "php_impl is not supported")
-        .to_compile_error()
-        .into()
+pub fn php_impl(_args: TokenStream, _input: TokenStream) -> TokenStream {
+    syn::Error::new(
+        Span::call_site(),
+        "php_impl can only be used inside a #[php_module] module",
+    )
+    .to_compile_error()
+    .into()
 }
 
+/// Exports a Rust constant as a global PHP constant. The constant can be any type that implements [`IntoConst`].
 #[proc_macro_attribute]
-pub fn php_const(_: TokenStream, input: TokenStream) -> TokenStream {
-    let mut input = parse_macro_input!(input as ItemConst);
-
-    match constant::parser(&mut input) {
-        Ok((parsed, _)) => parsed,
-        Err(e) => syn::Error::new(Span::call_site(), e).to_compile_error(),
-    }
+pub fn php_const(_args: TokenStream, _input: TokenStream) -> TokenStream {
+    syn::Error::new(
+        Span::call_site(),
+        "php_const can only be used inside a #[php_module] module",
+    )
+    .to_compile_error()
     .into()
 }
 
+/// Attribute used to annotate `extern` blocks which are deemed as PHP
+/// functions.
+///
+/// This allows you to 'import' PHP functions into Rust so that they can be
+/// called like regular Rust functions. Parameters can be any type that
+/// implements [`IntoZval`], and the return type can be anything that implements
+/// [`From<Zval>`] (notice how [`Zval`] is consumed rather than borrowed in this
+/// case).
 #[proc_macro_attribute]
 pub fn php_extern(_: TokenStream, input: TokenStream) -> TokenStream {
     let input = parse_macro_input!(input as ItemForeignMod);
@@ -150,6 +105,9 @@ pub fn php_extern(_: TokenStream, input: TokenStream) -> TokenStream {
     .into()
 }
 
+/// Derives the traits required to convert a struct or enum to and from a
+/// [`Zval`]. Both [`FromZval`] and [`IntoZval`] are implemented on types which
+/// use this macro.
 #[proc_macro_derive(ZvalConvert)]
 pub fn zval_convert_derive(input: TokenStream) -> TokenStream {
     let input = parse_macro_input!(input as DeriveInput);
@@ -161,6 +119,14 @@ pub fn zval_convert_derive(input: TokenStream) -> TokenStream {
     .into()
 }
 
+/// Defines an `extern` function with the Zend fastcall convention based on
+/// operating system.
+///
+/// On Windows, Zend fastcall functions use the vector calling convention, while
+/// on all other operating systems no fastcall convention is used (just the
+/// regular C calling convention).
+///
+/// This macro wraps a function and applies the correct calling convention.
 #[proc_macro]
 pub fn zend_fastcall(input: TokenStream) -> TokenStream {
     let input = parse_macro_input!(input as ItemFn);

crates/macros/src/module.rs

@@ -1,13 +1,15 @@
+use std::collections::HashMap;
+
 use anyhow::Result;
 use proc_macro2::{Ident, Span, TokenStream};
 use quote::quote;
 use syn::{Item, ItemMod, Type};
 
 use crate::{
     class::{Class, Property},
+    constant::Constant,
     function::{Arg, Function},
     module_builder::ModuleBuilder,
-    State,
 };
 
 pub fn parser(input: ItemMod) -> Result<TokenStream> {
@@ -25,19 +27,10 @@ pub fn parser(input: ItemMod) -> Result<TokenStream> {
     for item in content {
         match item {
             Item::Fn(f) => {
-                if f.attrs
-                    .iter()
-                    .find(|a| a.path.is_ident("php_startup"))
-                    .is_some()
-                {
+                if f.attrs.iter().any(|a| a.path.is_ident("php_startup")) {
                     builder.set_startup_function(f.clone());
                     continue;
-                } else if f
-                    .attrs
-                    .iter()
-                    .find(|a| a.path.is_ident("php_function"))
-                    .is_some()
-                {
+                } else if f.attrs.iter().any(|a| a.path.is_ident("php_function")) {
                     builder.add_function(f.clone());
                     continue;
                 }
@@ -47,21 +40,13 @@ pub fn parser(input: ItemMod) -> Result<TokenStream> {
                 continue;
             }
             Item::Struct(s) => {
-                if s.attrs
-                    .iter()
-                    .find(|a| a.path.is_ident("php_class"))
-                    .is_some()
-                {
+                if s.attrs.iter().any(|a| a.path.is_ident("php_class")) {
                     builder.add_class(s.clone());
                     continue;
                 }
             }
             Item::Impl(i) => {
-                if i.attrs
-                    .iter()
-                    .find(|a| a.path.is_ident("php_impl"))
-                    .is_some()
-                {
+                if i.attrs.iter().any(|a| a.path.is_ident("php_impl")) {
                     builder.add_implementation(i.clone());
                     continue;
                 }
@@ -142,8 +127,12 @@ pub trait Describe {
     fn describe(&self) -> TokenStream;
 }
 
-fn generate_stubs(state: &State) -> TokenStream {
-    let module = state.describe();
+pub(crate) fn generate_stubs(
+    functions: &[Function],
+    classes: &HashMap<String, Class>,
+    constants: &[Constant],
+) -> TokenStream {
+    let module = (functions, classes, constants).describe();
 
     quote! {
         #[cfg(debug_assertions)]
@@ -354,11 +343,11 @@ impl Describe for crate::constant::Constant {
     }
 }
 
-impl Describe for State {
+impl Describe for (&[Function], &HashMap<String, Class>, &[Constant]) {
     fn describe(&self) -> TokenStream {
-        let functs = self.functions.iter().map(Describe::describe);
-        let classes = self.classes.values().map(|class| class.describe());
-        let constants = self.constants.iter().map(Describe::describe);
+        let functs = self.0.iter().map(Describe::describe);
+        let classes = self.1.values().map(|class| class.describe());
+        let constants = self.2.iter().map(Describe::describe);
 
         quote! {
             Module {