diff --git a/gobject/gboxed.c b/gobject/gboxed.c
index ae48df566..e6bd786ab 100644
--- a/gobject/gboxed.c
+++ b/gobject/gboxed.c
@@ -283,6 +283,10 @@ boxed_proxy_lcopy_value (const GValue *value,
  * boxed type with name @name. Boxed type handling functions have to be
  * provided to copy and free opaque boxed structures of this type.
  *
+ * For the general case, it is recommended to use #G_DEFINE_BOXED_TYPE 
+ * instead of calling g_boxed_type_register_static() directly. The macro 
+ * will create the appropriate `*_get_type()` function for the boxed type.
+ *
  * Returns: New %G_TYPE_BOXED derived type id for @name.
  */
 GType
diff --git a/gobject/gtype.h b/gobject/gtype.h
index 5f9766978..f38b4cf4c 100644
--- a/gobject/gtype.h
+++ b/gobject/gtype.h
@@ -2071,8 +2071,24 @@ type_name##_get_type (void) \
  * @copy_func: the #GBoxedCopyFunc for the new type
  * @free_func: the #GBoxedFreeFunc for the new type
  *
- * A convenience macro for boxed type implementations, which defines a
- * type_name_get_type() function registering the boxed type.
+ * A convenience macro for defining a new custom boxed type. 
+ *
+ * Using this macro is the recommended way of defining new custom boxed
+ * types, over calling g_boxed_type_register_static() directly. It defines 
+ * a `type_name_get_type()` function which will return the newly defined
+ * #GType, enabling lazy instantiation.
+ *
+ * |[<!-- language="C" --> 
+ * G_DEFINE_BOXED_TYPE (MyStruct, my_struct, my_struct_copy, my_struct_free)
+ *
+ * void 
+ * foo ()
+ * {
+ *   GType type = my_struct_get_type ();
+ *   // ... your code ...
+ * }
+ *
+ * ]|
  *
  * Since: 2.26
  */