Skip to content

Commit 596ba24

Browse files
XeniraXenira
committed
docs(enum): extend enum documentation
Refs: #178
1 parent 70e91f3 commit 596ba24

File tree

7 files changed

+178
-45
lines changed

7 files changed

+178
-45
lines changed

‎.lefthook.yml

Lines changed: 5 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -17,8 +17,8 @@ pre-commit:
1717
The `docsrs_bindings.rs` file seems to be out of date.
1818
Please check the updated bindings in `docsrs_bindings.rs` and commit the changes.
1919
- name: "macro docs"
20-
run: tools/update_lib_docs.sh && git diff --exit-code crates/macros/src/lib.rs
21-
glob: "guide/src/macros/*.md"
22-
fail_text: |
23-
The macro crates documentation seems to be out of date.
24-
Please check the updated documentation in `crates/macros/src/lib.rs` and commit the changes.
20+
run: tools/update_lib_docs.sh
21+
glob:
22+
- "guide/src/macros/*.md"
23+
- "crates/macros/src/lib.rs"
24+
stage_fixed: true

‎crates/macros/src/enum_.rs

Lines changed: 1 addition & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -20,6 +20,7 @@ struct PhpEnumAttribute {
2020
#[darling(default)]
2121
allow_native_discriminants: Flag,
2222
rename_cases: Option<RenameRule>,
23+
// TODO: Implement visibility support
2324
vis: Option<Visibility>,
2425
attrs: Vec<syn::Attribute>,
2526
}
@@ -30,8 +31,6 @@ struct PhpEnumVariantAttribute {
3031
#[darling(flatten)]
3132
rename: PhpRename,
3233
discriminant: Option<Lit>,
33-
// TODO: Implement doc support for enum variants
34-
#[allow(dead_code)]
3534
attrs: Vec<syn::Attribute>,
3635
}
3736

@@ -342,7 +341,6 @@ impl ToTokens for Enum<'_> {
342341

343342
#[derive(Debug)]
344343
struct EnumCase {
345-
#[allow(dead_code)]
346344
ident: Ident,
347345
name: String,
348346
#[allow(dead_code)]

‎crates/macros/src/lib.rs

Lines changed: 79 additions & 8 deletions
Original file line numberDiff line numberDiff line change
@@ -221,18 +221,28 @@ fn php_class_internal(args: TokenStream2, input: TokenStream2) -> TokenStream2 {
221221
///
222222
/// Enums can be exported to PHP as enums with the `#[php_enum]` attribute
223223
/// macro. This attribute derives the `RegisteredClass` and `PhpEnum` traits on
224-
/// your enum. To register the enum use the `r#enum::<EnumName>()` method on the
225-
/// `ModuleBuilder` in the `#[php_module]` macro.
224+
/// your enum. To register the enum use the `enumeration::<EnumName>()` method
225+
/// on the `ModuleBuilder` in the `#[php_module]` macro.
226226
///
227227
/// ## Options
228228
///
229-
/// tbd
229+
/// The `#[php_enum]` attribute can be configured with the following options:
230+
/// - `#[php(name = "EnumName")]` or `#[php(change_case = snake_case)]`: Sets
231+
/// the name of the enum in PHP. The default is the `PascalCase` name of the
232+
/// enum.
233+
/// - `#[php(allow_native_discriminants)]`: Allows the use of native Rust
234+
/// discriminants (e.g., `Hearts = 1`).
230235
///
231-
/// ## Restrictions
232-
///
233-
/// tbd
236+
/// The cases of the enum can be configured with the following options:
237+
/// - `#[php(name = "CaseName")]` or `#[php(change_case = snake_case)]`: Sets
238+
/// the name of the enum case in PHP. The default is the `PascalCase` name of
239+
/// the case.
240+
/// - `#[php(discriminant = "value")]` or `#[php(discriminant = 123)]`: Sets the
241+
/// discriminant value for the enum case. This can be a string or an integer.
242+
/// If not set, the case will be exported as a simple enum case without a
243+
/// discriminant.
234244
///
235-
/// ## Example
245+
/// ### Example
236246
///
237247
/// This example creates a PHP enum `Suit`.
238248
///
@@ -251,11 +261,72 @@ fn php_class_internal(args: TokenStream2, input: TokenStream2) -> TokenStream2 {
251261
///
252262
/// #[php_module]
253263
/// pub fn get_module(module: ModuleBuilder) -> ModuleBuilder {
254-
/// module.r#enum::<Suit>()
264+
/// module.enumeration::<Suit>()
255265
/// }
256266
/// # fn main() {}
257267
/// ```
258268
///
269+
/// ## Backed Enums
270+
/// Enums can also be backed by either `i64` or `&'static str`. Those values can
271+
/// be set using the `#[php(discriminant = "value")]` or `#[php(discriminant =
272+
/// 123)]` attributes on the enum variants.
273+
///
274+
/// All variants must have a discriminant of the same type, either all `i64` or
275+
/// all `&'static str`.
276+
///
277+
/// ```rust,no_run,ignore
278+
/// # #![cfg_attr(windows, feature(abi_vectorcall))]
279+
/// # extern crate ext_php_rs;
280+
/// use ext_php_rs::prelude::*;
281+
///
282+
/// #[php_enum]
283+
/// pub enum Suit {
284+
/// #[php(discriminant = "hearts")]
285+
/// Hearts,
286+
/// #[php(discriminant = "diamonds")]
287+
/// Diamonds,
288+
/// #[php(discriminant = "clubs")]
289+
/// Clubs,
290+
/// #[php(discriminant = "spades")]
291+
/// Spades,
292+
/// }
293+
/// #[php_module]
294+
/// pub fn get_module(module: ModuleBuilder) -> ModuleBuilder {
295+
/// module.enumeration::<Suit>()
296+
/// }
297+
/// # fn main() {}
298+
/// ```
299+
///
300+
/// ### 'Native' Discriminators
301+
/// Native rust discriminants are currently not supported and will not be
302+
/// exported to PHP.
303+
///
304+
/// To avoid confusion a compiler error will be raised if you try to use a
305+
/// native discriminant. You can ignore this error by adding the
306+
/// `#[php(allow_native_discriminants)]` attribute to your enum.
307+
///
308+
/// ```rust,no_run,ignore
309+
/// # #![cfg_attr(windows, feature(abi_vectorcall))]
310+
/// # extern crate ext_php_rs;
311+
/// use ext_php_rs::prelude::*;
312+
///
313+
/// #[php_enum]
314+
/// #[php(allow_native_discriminants)]
315+
/// pub enum Suit {
316+
/// Hearts = 1,
317+
/// Diamonds = 2,
318+
/// Clubs = 3,
319+
/// Spades = 4,
320+
/// }
321+
///
322+
/// #[php_module]
323+
/// pub fn get_module(module: ModuleBuilder) -> ModuleBuilder {
324+
/// module.enumeration::<Suit>()
325+
/// }
326+
/// # fn main() {}
327+
/// ```
328+
///
329+
///
259330
/// TODO: Add backed enums example
260331
// END DOCS FROM enum.md
261332
#[proc_macro_attribute]

‎guide/src/macros/enum.md

Lines changed: 69 additions & 7 deletions
Original file line numberDiff line numberDiff line change
@@ -2,18 +2,23 @@
22

33
Enums can be exported to PHP as enums with the `#[php_enum]` attribute macro.
44
This attribute derives the `RegisteredClass` and `PhpEnum` traits on your enum.
5-
To register the enum use the `r#enum::<EnumName>()` method on the `ModuleBuilder`
5+
To register the enum use the `enumeration::<EnumName>()` method on the `ModuleBuilder`
66
in the `#[php_module]` macro.
77

88
## Options
99

10-
tbd
10+
The `#[php_enum]` attribute can be configured with the following options:
11+
- `#[php(name = "EnumName")]` or `#[php(change_case = snake_case)]`: Sets the name of the enum in PHP.
12+
The default is the `PascalCase` name of the enum.
13+
- `#[php(allow_native_discriminants)]`: Allows the use of native Rust discriminants (e.g., `Hearts = 1`).
1114

12-
## Restrictions
15+
The cases of the enum can be configured with the following options:
16+
- `#[php(name = "CaseName")]` or `#[php(change_case = snake_case)]`: Sets the name of the enum case in PHP.
17+
The default is the `PascalCase` name of the case.
18+
- `#[php(discriminant = "value")]` or `#[php(discriminant = 123)]`: Sets the discriminant value for the enum case.
19+
This can be a string or an integer. If not set, the case will be exported as a simple enum case without a discriminant.
1320

14-
tbd
15-
16-
## Example
21+
### Example
1722

1823
This example creates a PHP enum `Suit`.
1924

@@ -32,9 +37,66 @@ pub enum Suit {
3237
3338
#[php_module]
3439
pub fn get_module(module: ModuleBuilder) -> ModuleBuilder {
35-
module.r#enum::<Suit>()
40+
module.enumeration::<Suit>()
3641
}
3742
# fn main() {}
3843
```
3944

45+
## Backed Enums
46+
Enums can also be backed by either `i64` or `&'static str`. Those values can be set using the
47+
`#[php(discriminant = "value")]` or `#[php(discriminant = 123)]` attributes on the enum variants.
48+
49+
All variants must have a discriminant of the same type, either all `i64` or all `&'static str`.
50+
51+
```rust,no_run
52+
# #![cfg_attr(windows, feature(abi_vectorcall))]
53+
# extern crate ext_php_rs;
54+
use ext_php_rs::prelude::*;
55+
56+
#[php_enum]
57+
pub enum Suit {
58+
#[php(discriminant = "hearts")]
59+
Hearts,
60+
#[php(discriminant = "diamonds")]
61+
Diamonds,
62+
#[php(discriminant = "clubs")]
63+
Clubs,
64+
#[php(discriminant = "spades")]
65+
Spades,
66+
}
67+
#[php_module]
68+
pub fn get_module(module: ModuleBuilder) -> ModuleBuilder {
69+
module.enumeration::<Suit>()
70+
}
71+
# fn main() {}
72+
```
73+
74+
### 'Native' Discriminators
75+
Native rust discriminants are currently not supported and will not be exported to PHP.
76+
77+
To avoid confusion a compiler error will be raised if you try to use a native discriminant.
78+
You can ignore this error by adding the `#[php(allow_native_discriminants)]` attribute to your enum.
79+
80+
```rust,no_run
81+
# #![cfg_attr(windows, feature(abi_vectorcall))]
82+
# extern crate ext_php_rs;
83+
use ext_php_rs::prelude::*;
84+
85+
#[php_enum]
86+
#[php(allow_native_discriminants)]
87+
pub enum Suit {
88+
Hearts = 1,
89+
Diamonds = 2,
90+
Clubs = 3,
91+
Spades = 4,
92+
}
93+
94+
#[php_module]
95+
pub fn get_module(module: ModuleBuilder) -> ModuleBuilder {
96+
module.enumeration::<Suit>()
97+
}
98+
# fn main() {}
99+
```
100+
101+
40102
TODO: Add backed enums example

‎guide/src/macros/php.md

Lines changed: 20 additions & 18 deletions
Original file line numberDiff line numberDiff line change
@@ -33,24 +33,26 @@ fn hello_world(a: i32, b: i32) -> i32 {
3333

3434
Which attributes are available depends on the element you are annotating:
3535

36-
| Attribute | `const` | `fn` | `struct` | `struct` field | `impl` | `impl` `const` | `impl` `fn` |
37-
| -------------------- | ------- | ---- | -------- | -------------- | ------ | -------------- | ----------- |
38-
| name | ✅ | ✅ | ✅ | ✅ | ❌ | ✅ | ✅ |
39-
| change_case | ✅ | ✅ | ✅ | ✅ | ❌ | ✅ | ✅ |
40-
| change_method_case | ❌ | ❌ | ❌ | ❌ | ✅ | ❌ | ❌ |
41-
| change_constant_case | ❌ | ❌ | ❌ | ❌ | ✅ | ❌ | ❌ |
42-
| flags | ❌ | ❌ | ✅ | ✅ | ❌ | ❌ | ❌ |
43-
| prop | ❌ | ❌ | ❌ | ✅ | ❌ | ❌ | ❌ |
44-
| extends | ❌ | ❌ | ✅ | ❌ | ❌ | ❌ | ❌ |
45-
| implements | ❌ | ❌ | ✅ | ❌ | ❌ | ❌ | ❌ |
46-
| modifier | ❌ | ❌ | ✅ | ❌ | ❌ | ❌ | ❌ |
47-
| defaults | ❌ | ✅ | ❌ | ❌ | ❌ | ❌ | ✅ |
48-
| optional | ❌ | ✅ | ❌ | ❌ | ❌ | ❌ | ✅ |
49-
| vis | ❌ | ✅ | ❌ | ❌ | ❌ | ❌ | ✅ |
50-
| getter | ❌ | ❌ | ❌ | ❌ | ❌ | ❌ | ✅ |
51-
| setter | ❌ | ❌ | ❌ | ❌ | ❌ | ❌ | ✅ |
52-
| constructor | ❌ | ❌ | ❌ | ❌ | ❌ | ❌ | ✅ |
53-
| abstract_method | ❌ | ❌ | ❌ | ❌ | ❌ | ❌ | ✅ |
36+
| Attribute | `const` | `fn` | `struct` | `struct` field | `impl` | `impl` `const` | `impl` `fn` | `enum` | `enum` case |
37+
| -------------------------- | ------- | ---- | -------- | -------------- | ------ | -------------- | ----------- | ------ | ----------- |
38+
| name | ✅ | ✅ | ✅ | ✅ | ❌ | ✅ | ✅ | ✅ | ✅ |
39+
| change_case | ✅ | ✅ | ✅ | ✅ | ❌ | ✅ | ✅ | ✅ | ✅ |
40+
| change_method_case | ❌ | ❌ | ❌ | ❌ | ✅ | ❌ | ❌ | ❌ | ❌ |
41+
| change_constant_case | ❌ | ❌ | ❌ | ❌ | ✅ | ❌ | ❌ | ❌ | ❌ |
42+
| flags | ❌ | ❌ | ✅ | ✅ | ❌ | ❌ | ❌ | ❌ | ❌ |
43+
| prop | ❌ | ❌ | ❌ | ✅ | ❌ | ❌ | ❌ | ❌ | ❌ |
44+
| extends | ❌ | ❌ | ✅ | ❌ | ❌ | ❌ | ❌ | ❌ | ❌ |
45+
| implements | ❌ | ❌ | ✅ | ❌ | ❌ | ❌ | ❌ | ❌ | ❌ |
46+
| modifier | ❌ | ❌ | ✅ | ❌ | ❌ | ❌ | ❌ | ❌ | ❌ |
47+
| defaults | ❌ | ✅ | ❌ | ❌ | ❌ | ❌ | ✅ | ❌ | ❌ |
48+
| optional | ❌ | ✅ | ❌ | ❌ | ❌ | ❌ | ✅ | ❌ | ❌ |
49+
| vis | ❌ | ✅ | ❌ | ❌ | ❌ | ❌ | ✅ | ❌ | ❌ |
50+
| getter | ❌ | ❌ | ❌ | ❌ | ❌ | ❌ | ✅ | ❌ | ❌ |
51+
| setter | ❌ | ❌ | ❌ | ❌ | ❌ | ❌ | ✅ | ❌ | ❌ |
52+
| constructor | ❌ | ❌ | ❌ | ❌ | ❌ | ❌ | ✅ | ❌ | ❌ |
53+
| abstract_method | ❌ | ❌ | ❌ | ❌ | ❌ | ❌ | ✅ | ❌ | ❌ |
54+
| allow_native_discriminants | ❌ | ❌ | ❌ | ❌ | ❌ | ❌ | ❌ | ✅ | ❌ |
55+
| discriminant | ❌ | ❌ | ❌ | ❌ | ❌ | ❌ | ❌ | ❌ | ✅ |
5456

5557
## `name` and `change_case`
5658

‎src/builders/module.rs

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -213,7 +213,7 @@ impl ModuleBuilder<'_> {
213213

214214
/// Adds an enum to the extension.
215215
#[cfg(feature = "enum")]
216-
pub fn r#enum<T>(mut self) -> Self
216+
pub fn enumeration<T>(mut self) -> Self
217217
where
218218
T: RegisteredClass + RegisteredEnum,
219219
{

‎tests/src/integration/enum_/mod.rs

Lines changed: 3 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -40,9 +40,9 @@ pub fn test_enum(a: TestEnum) -> Result<StringBackedEnum> {
4040

4141
pub fn build_module(builder: ModuleBuilder) -> ModuleBuilder {
4242
builder
43-
.r#enum::<TestEnum>()
44-
.r#enum::<IntBackedEnum>()
45-
.r#enum::<StringBackedEnum>()
43+
.enumeration::<TestEnum>()
44+
.enumeration::<IntBackedEnum>()
45+
.enumeration::<StringBackedEnum>()
4646
.function(wrap_function!(test_enum))
4747
}
4848

0 commit comments

Comments
 (0)