feat(enum): add stub generation

Refs: #178

Author: Xenira

src/builders/enum_builder.rs

@@ -2,6 +2,7 @@ use std::{ffi::CString, ptr};
 
 use crate::{
     builders::FunctionBuilder,
+    describe::DocComments,
     enum_::EnumCase,
     error::Result,
     ffi::{zend_enum_add_case, zend_register_internal_enum},
@@ -10,26 +11,35 @@ use crate::{
     zend::{ClassEntry, FunctionEntry},
 };
 
+/// A builder for PHP enums.
 #[must_use]
 pub struct EnumBuilder {
     pub(crate) name: String,
     pub(crate) methods: Vec<(FunctionBuilder<'static>, MethodFlags)>,
     pub(crate) cases: Vec<&'static EnumCase>,
     pub(crate) datatype: DataType,
     register: Option<fn(&'static mut ClassEntry)>,
+    pub(crate) docs: DocComments,
 }
 
 impl EnumBuilder {
+    /// Creates a new enum builder with the given name.
     pub fn new<T: Into<String>>(name: T) -> Self {
         Self {
             name: name.into(),
             methods: Vec::default(),
             cases: Vec::default(),
             datatype: DataType::Undef,
             register: None,
+            docs: DocComments::default(),
         }
     }
 
+    /// Adds an enum case to the enum.
+    ///
+    /// # Panics
+    ///
+    /// If the case's data type does not match the enum's data type
     pub fn case(mut self, case: &'static EnumCase) -> Self {
         let data_type = case.data_type();
         assert!(
@@ -45,7 +55,8 @@ impl EnumBuilder {
         self
     }
 
-    pub fn add_method(mut self, method: FunctionBuilder<'static>, flags: MethodFlags) -> Self {
+    /// Adds a method to the enum.
+    pub fn method(mut self, method: FunctionBuilder<'static>, flags: MethodFlags) -> Self {
         self.methods.push((method, flags));
         self
     }
@@ -61,6 +72,23 @@ impl EnumBuilder {
         self
     }
 
+    /// Add documentation comments to the enum.
+    pub fn docs(mut self, docs: DocComments) -> Self {
+        self.docs = docs;
+        self
+    }
+
+    /// Registers the enum with PHP.
+    ///
+    /// # Panics
+    ///
+    /// If the registration function was not set prior to calling this
+    /// method.
+    ///
+    /// # Errors
+    ///
+    /// If the enum could not be registered, e.g. due to an invalid name or
+    /// data type.
     pub fn register(self) -> Result<()> {
         let mut methods = self
             .methods

src/builders/mod.rs

@@ -12,6 +12,8 @@ mod module;
 mod sapi;
 
 pub use class::ClassBuilder;
+#[cfg(feature = "enum")]
+pub use enum_builder::EnumBuilder;
 pub use function::FunctionBuilder;
 #[cfg(all(php82, feature = "embed"))]
 pub use ini::IniBuilder;

src/builders/module.rs

@@ -223,12 +223,14 @@ impl ModuleBuilder<'_> {
                 builder = builder.case(case);
             }
             for (method, flags) in T::method_builders() {
-                builder = builder.add_method(method, flags);
+                builder = builder.method(method, flags);
             }
 
-            builder.registration(|ce| {
-                T::get_metadata().set_ce(ce);
-            })
+            builder
+                .registration(|ce| {
+                    T::get_metadata().set_ce(ce);
+                })
+                .docs(T::DOC_COMMENTS)
         });
 
         self

src/describe/mod.rs

@@ -2,6 +2,8 @@
 //! CLI application to generate PHP stub files used by IDEs.
 use std::vec::Vec as StdVec;
 
+#[cfg(feature = "enum")]
+use crate::builders::EnumBuilder;
 use crate::{
     builders::{ClassBuilder, FunctionBuilder},
     constant::IntoConst,
@@ -67,6 +69,9 @@ pub struct Module {
     pub functions: Vec<Function>,
     /// Classes exported by the extension.
     pub classes: Vec<Class>,
+    #[cfg(feature = "enum")]
+    /// Enums exported by the extension.
+    pub enums: Vec<Enum>,
     /// Constants exported by the extension.
     pub constants: Vec<Constant>,
 }
@@ -95,6 +100,13 @@ impl From<ModuleBuilder<'_>> for Module {
                 .map(Constant::from)
                 .collect::<StdVec<_>>()
                 .into(),
+            #[cfg(feature = "enum")]
+            enums: builder
+                .enums
+                .into_iter()
+                .map(|e| e().into())
+                .collect::<StdVec<_>>()
+                .into(),
         }
     }
 }
@@ -216,6 +228,86 @@ impl From<ClassBuilder> for Class {
     }
 }
 
+#[cfg(feature = "enum")]
+/// Represents an exported enum.
+#[repr(C)]
+#[derive(Debug, PartialEq)]
+pub struct Enum {
+    /// Name of the enum.
+    pub name: RString,
+    /// Documentation comments for the enum.
+    pub docs: DocBlock,
+    /// Cases of the enum.
+    pub cases: Vec<EnumCase>,
+    /// Backing type of the enum.
+    pub backing_type: Option<RString>,
+}
+
+#[cfg(feature = "enum")]
+impl From<EnumBuilder> for Enum {
+    fn from(val: EnumBuilder) -> Self {
+        Self {
+            name: val.name.into(),
+            docs: DocBlock(
+                val.docs
+                    .iter()
+                    .map(|d| (*d).into())
+                    .collect::<StdVec<_>>()
+                    .into(),
+            ),
+            cases: val
+                .cases
+                .into_iter()
+                .map(EnumCase::from)
+                .collect::<StdVec<_>>()
+                .into(),
+            backing_type: match val.datatype {
+                DataType::Long => Some("int".into()),
+                DataType::String => Some("string".into()),
+                _ => None,
+            }
+            .into(),
+        }
+    }
+}
+
+#[cfg(feature = "enum")]
+/// Represents a case in an exported enum.
+#[repr(C)]
+#[derive(Debug, PartialEq)]
+pub struct EnumCase {
+    /// Name of the enum case.
+    pub name: RString,
+    /// Documentation comments for the enum case.
+    pub docs: DocBlock,
+    /// Value of the enum case.
+    pub value: Option<RString>,
+}
+
+#[cfg(feature = "enum")]
+impl From<&'static crate::enum_::EnumCase> for EnumCase {
+    fn from(val: &'static crate::enum_::EnumCase) -> Self {
+        Self {
+            name: val.name.into(),
+            docs: DocBlock(
+                val.docs
+                    .iter()
+                    .map(|d| (*d).into())
+                    .collect::<StdVec<_>>()
+                    .into(),
+            ),
+            value: val
+                .discriminant
+                .as_ref()
+                .map(|v| match v {
+                    crate::enum_::Discriminant::Int(i) => i.to_string().into(),
+                    crate::enum_::Discriminant::String(s) => format!("'{s}'").into(),
+                })
+                .into(),
+        }
+    }
+}
+
 /// Represents a property attached to an exported class.
 #[repr(C)]
 #[derive(Debug, PartialEq)]
@@ -437,6 +529,8 @@ mod tests {
             functions: vec![].into(),
             classes: vec![].into(),
             constants: vec![].into(),
+            #[cfg(feature = "enum")]
+            enums: vec![].into(),
         };
 
         let description = Description::new(module);

src/describe/stub.rs

@@ -1,15 +1,22 @@
 //! Traits and implementations to convert describe units into PHP stub code.
 
-use crate::flags::DataType;
-use std::{cmp::Ordering, collections::HashMap};
+use std::{
+    cmp::Ordering,
+    collections::HashMap,
+    fmt::{Error as FmtError, Result as FmtResult, Write},
+    option::Option as StdOption,
+    vec::Vec as StdVec,
+};
 
 use super::{
     abi::{Option, RString},
     Class, Constant, DocBlock, Function, Method, MethodType, Module, Parameter, Property,
     Visibility,
 };
-use std::fmt::{Error as FmtError, Result as FmtResult, Write};
-use std::{option::Option as StdOption, vec::Vec as StdVec};
+
+#[cfg(feature = "enum")]
+use crate::describe::{Enum, EnumCase};
+use crate::flags::DataType;
 
 /// Implemented on types which can be converted into PHP stubs.
 pub trait ToStub {
@@ -78,6 +85,12 @@ impl ToStub for Module {
             insert(ns, class.to_stub()?);
         }
 
+        #[cfg(feature = "enum")]
+        for r#enum in &*self.enums {
+            let (ns, _) = split_namespace(r#enum.name.as_ref());
+            insert(ns, r#enum.to_stub()?);
+        }
+
         let mut entries: StdVec<_> = entries.iter().collect();
         entries.sort_by(|(l, _), (r, _)| match (l, r) {
             (None, _) => Ordering::Greater,
@@ -241,6 +254,41 @@ impl ToStub for Class {
     }
 }
 
+#[cfg(feature = "enum")]
+impl ToStub for Enum {
+    fn fmt_stub(&self, buf: &mut String) -> FmtResult {
+        self.docs.fmt_stub(buf)?;
+
+        let (_, name) = split_namespace(self.name.as_ref());
+        write!(buf, "enum {name}")?;
+
+        if let Option::Some(backing_type) = &self.backing_type {
+            write!(buf, ": {backing_type}")?;
+        }
+
+        writeln!(buf, " {{")?;
+
+        for case in self.cases.iter() {
+            case.fmt_stub(buf)?;
+        }
+
+        writeln!(buf, "}}")
+    }
+}
+
+#[cfg(feature = "enum")]
+impl ToStub for EnumCase {
+    fn fmt_stub(&self, buf: &mut String) -> FmtResult {
+        self.docs.fmt_stub(buf)?;
+
+        write!(buf, "  case {}", self.name)?;
+        if let Option::Some(value) = &self.value {
+            write!(buf, " = {value}")?;
+        }
+        writeln!(buf, ";")
+    }
+}
+
 impl ToStub for Property {
     fn fmt_stub(&self, buf: &mut String) -> FmtResult {
         self.docs.fmt_stub(buf)?;

tests/src/integration/enum_/mod.rs

@@ -2,10 +2,14 @@ use ext_php_rs::{error::Result, php_enum, php_function, prelude::ModuleBuilder,
 
 #[php_enum]
 #[php(allow_native_discriminants)]
+/// An example enum that demonstrates how to use PHP enums with Rust.
+/// This enum has two variants, `Variant1` and `Variant2`.
 pub enum TestEnum {
-    // #[php(discriminant = 2)]
+    /// Represents the first variant of the enum.
+    /// This variant has a discriminant of 0.
+    /// But PHP does not know about it.
     Variant1,
-    // #[php(discriminant = 1)]
+    /// Represents the second variant of the enum.
     Variant2 = 1,
 }