Merge pull request #1732 from nozwock/document-enum-macro

Document requirement for explicit default in `Enum` properties

Author: sdroege

glib-macros/src/lib.rs

@@ -525,6 +525,10 @@ pub fn closure_local(item: TokenStream) -> TokenStream {
 /// }
 /// ```
 ///
+/// When using the [`Properties`] macro with enums that derive [`Enum`], the default value must be
+/// explicitly set via the `builder` parameter of the `#[property]` attribute. See
+/// [here](Properties#supported-types) for details.
+///
 /// An enum can be registered as a dynamic type by setting the derive macro
 /// helper attribute `enum_dynamic`:
 ///
@@ -1366,6 +1370,9 @@ pub fn cstr_bytes(item: TokenStream) -> TokenStream {
 /// Optional types also require the `nullable` attribute: without it, the generated setter on the wrapper type
 /// will take `T` instead of `Option<T>`, preventing the user from ever calling the setter with a `None` value.
 ///
+/// Notice: For enums that derive [`Enum`] or are C-style enums, you must explicitly specify the
+/// default value of the enum using the `builder` parameter in the `#[property]` attribute.
+///
 /// ## Adding support for custom types
 /// ### Types wrapping an existing <code>T: [ToValue] + [HasParamSpec]</code>
 /// If you have declared a newtype as
@@ -1390,7 +1397,7 @@ pub fn cstr_bytes(item: TokenStream) -> TokenStream {
 ///
 /// # Example
 /// ```
-/// use std::cell::RefCell;
+/// use std::cell::{Cell, RefCell};
 /// use glib::prelude::*;
 /// use glib::subclass::prelude::*;
 /// use glib_macros::Properties;
@@ -1401,6 +1408,14 @@ pub fn cstr_bytes(item: TokenStream) -> TokenStream {
 ///     nick: String,
 /// }
 ///
+/// #[derive(Debug, Copy, Clone, PartialEq, Eq, glib::Enum, Default)]
+/// #[enum_type(name = "MyEnum")]
+/// enum MyEnum {
+///     #[default]
+///     Val,
+///     OtherVal
+/// }
+///
 /// pub mod imp {
 ///     use std::rc::Rc;
 ///
@@ -1426,6 +1441,8 @@ pub fn cstr_bytes(item: TokenStream) -> TokenStream {
 ///         optional: RefCell<Option<String>>,
 ///         #[property(get, set)]
 ///         smart_pointer: Rc<RefCell<String>>,
+///         #[property(get, set, builder(MyEnum::Val))]
+///         my_enum: Cell<MyEnum>,
 ///         /// # Getter
 ///         ///
 ///         /// Get the value of the property `extra_comments`