From c1e0506d868275d2ca6f4edca86b8503467d5085 Mon Sep 17 00:00:00 2001 From: Philip Withnall Date: Thu, 13 Apr 2023 13:51:04 +0100 Subject: [PATCH 1/3] gtype: Clarify return value documentation MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit ‘returns TRUE on success’ is misleading for a lot of these macros, as they are checking whether a type has a certain property. Such a check could be successful but return `FALSE`, by the normal meaning of the word ‘success’. Instead, reword the docs to spell out when `TRUE` will be returned. Signed-off-by: Philip Withnall --- gobject/gtype.h | 36 ++++++++++++++++++------------------ 1 file changed, 18 insertions(+), 18 deletions(-) diff --git a/gobject/gtype.h b/gobject/gtype.h index cba70185e..a555a90dd 100644 --- a/gobject/gtype.h +++ b/gobject/gtype.h @@ -268,7 +268,7 @@ G_BEGIN_DECLS * * Checks if @type is a fundamental type. * - * Returns: %TRUE on success + * Returns: %TRUE is @type is fundamental */ #define G_TYPE_IS_FUNDAMENTAL(type) ((type) <= G_TYPE_FUNDAMENTAL_MAX) /** @@ -279,7 +279,7 @@ G_BEGIN_DECLS * inherited) from another type (this holds true for all non-fundamental * types). * - * Returns: %TRUE on success + * Returns: %TRUE if @type is derived */ #define G_TYPE_IS_DERIVED(type) ((type) > G_TYPE_FUNDAMENTAL_MAX) /** @@ -295,7 +295,7 @@ G_BEGIN_DECLS * with the difference that GType interfaces are not derivable (but see * g_type_interface_add_prerequisite() for an alternative). * - * Returns: %TRUE on success + * Returns: %TRUE if @type is an interface */ #define G_TYPE_IS_INTERFACE(type) (G_TYPE_FUNDAMENTAL (type) == G_TYPE_INTERFACE) /** @@ -304,7 +304,7 @@ G_BEGIN_DECLS * * Checks if @type is a classed type. * - * Returns: %TRUE on success + * Returns: %TRUE if @type is classed */ #define G_TYPE_IS_CLASSED(type) (g_type_test_flags ((type), G_TYPE_FLAG_CLASSED)) /** @@ -314,7 +314,7 @@ G_BEGIN_DECLS * Checks if @type can be instantiated. Instantiation is the * process of creating an instance (object) of this type. * - * Returns: %TRUE on success + * Returns: %TRUE if @type is instantiatable */ #define G_TYPE_IS_INSTANTIATABLE(type) (g_type_test_flags ((type), G_TYPE_FLAG_INSTANTIATABLE)) /** @@ -324,7 +324,7 @@ G_BEGIN_DECLS * Checks if @type is a derivable type. A derivable type can * be used as the base class of a flat (single-level) class hierarchy. * - * Returns: %TRUE on success + * Returns: %TRUE if @type is derivable */ #define G_TYPE_IS_DERIVABLE(type) (g_type_test_flags ((type), G_TYPE_FLAG_DERIVABLE)) /** @@ -334,7 +334,7 @@ G_BEGIN_DECLS * Checks if @type is a deep derivable type. A deep derivable type * can be used as the base class of a deep (multi-level) class hierarchy. * - * Returns: %TRUE on success + * Returns: %TRUE if @type is deep derivable */ #define G_TYPE_IS_DEEP_DERIVABLE(type) (g_type_test_flags ((type), G_TYPE_FLAG_DEEP_DERIVABLE)) /** @@ -345,7 +345,7 @@ G_BEGIN_DECLS * instantiated and is normally used as an abstract base class for * derived classes. * - * Returns: %TRUE on success + * Returns: %TRUE if @type is abstract */ #define G_TYPE_IS_ABSTRACT(type) (g_type_test_flags ((type), G_TYPE_FLAG_ABSTRACT)) /** @@ -356,7 +356,7 @@ G_BEGIN_DECLS * a value table, but can't be used for g_value_init() and is normally used as * an abstract base type for derived value types. * - * Returns: %TRUE on success + * Returns: %TRUE if @type is an abstract value type */ #define G_TYPE_IS_VALUE_ABSTRACT(type) (g_type_test_flags ((type), G_TYPE_FLAG_VALUE_ABSTRACT)) /** @@ -365,7 +365,7 @@ G_BEGIN_DECLS * * Checks if @type is a value type and can be used with g_value_init(). * - * Returns: %TRUE on success + * Returns: %TRUE if @type is a value type */ #define G_TYPE_IS_VALUE_TYPE(type) (g_type_check_is_value_type (type)) /** @@ -374,7 +374,7 @@ G_BEGIN_DECLS * * Checks if @type has a #GTypeValueTable. * - * Returns: %TRUE on success + * Returns: %TRUE if @type has a value table */ #define G_TYPE_HAS_VALUE_TABLE(type) (g_type_value_table_peek (type) != NULL) /** @@ -384,7 +384,7 @@ G_BEGIN_DECLS * Checks if @type is a final type. A final type cannot be derived any * further. * - * Returns: %TRUE on success + * Returns: %TRUE if @type is final * * Since: 2.70 */ @@ -497,7 +497,7 @@ struct _GTypeQuery * * This macro should only be used in type implementations. * - * Returns: %TRUE on success + * Returns: %TRUE if @instance is valid */ #define G_TYPE_CHECK_INSTANCE(instance) (_G_TYPE_CHI ((GTypeInstance*) (instance))) /** @@ -525,7 +525,7 @@ struct _GTypeQuery * * This macro should only be used in type implementations. * - * Returns: %TRUE on success + * Returns: %TRUE if @instance is an instance of @g_type */ #define G_TYPE_CHECK_INSTANCE_TYPE(instance, g_type) (_G_TYPE_CIT ((instance), (g_type))) /** @@ -538,7 +538,7 @@ struct _GTypeQuery * * This macro should only be used in type implementations. * - * Returns: %TRUE on success + * Returns: %TRUE if @instance is an instance of @g_type */ #define G_TYPE_CHECK_INSTANCE_FUNDAMENTAL_TYPE(instance, g_type) (_G_TYPE_CIFT ((instance), (g_type))) /** @@ -594,7 +594,7 @@ struct _GTypeQuery * * This macro should only be used in type implementations. * - * Returns: %TRUE on success + * Returns: %TRUE if @g_class is a class structure of @g_type */ #define G_TYPE_CHECK_CLASS_TYPE(g_class, g_type) (_G_TYPE_CCT ((g_class), (g_type))) /** @@ -606,7 +606,7 @@ struct _GTypeQuery * * This macro should only be used in type implementations. * - * Returns: %TRUE on success + * Returns: %TRUE if @value is initialized */ #define G_TYPE_CHECK_VALUE(value) (_G_TYPE_CHV ((value))) /** @@ -619,7 +619,7 @@ struct _GTypeQuery * * This macro should only be used in type implementations. * - * Returns: %TRUE on success + * Returns: %TRUE if @value has been initialized to hold values of type @g_type */ #define G_TYPE_CHECK_VALUE_TYPE(value, g_type) (_G_TYPE_CVH ((value), (g_type))) /** From 783f1b8640089f41af5862cb8e6ab092efe2b26f Mon Sep 17 00:00:00 2001 From: Philip Withnall Date: Thu, 13 Apr 2023 15:37:00 +0100 Subject: [PATCH 2/3] gtype: Improve documentation for G_TYPE_IS_CLASSED and interfaces MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit The documentation previously implicitly said in a few places that interfaces are classed, but reading through the implementation of `GType`, I don’t think they are. If they were, the registration of the fundamental `G_TYPE_INTERFACE` in `gobject_init()` would specify `G_TYPE_FLAG_CLASSED`. It only specifies `G_TYPE_FLAG_DERIVABLE`. I think this makes sense, because you can’t subclass an interface. Subclassing is a key property of being classed. Tweak the `GType` tutorial to remove that implicit statement, and expand the documentation for `G_TYPE_IS_CLASSED`. Signed-off-by: Philip Withnall Fixes: #252 --- docs/reference/gobject/tut_gobject.xml | 2 +- docs/reference/gobject/tut_gtype.xml | 16 ++++++++-------- docs/reference/gobject/tut_howto.xml | 2 +- gobject/gtype.h | 9 +++++++++ 4 files changed, 19 insertions(+), 10 deletions(-) diff --git a/docs/reference/gobject/tut_gobject.xml b/docs/reference/gobject/tut_gobject.xml index 7a2ecc77e..7754fec1e 100644 --- a/docs/reference/gobject/tut_gobject.xml +++ b/docs/reference/gobject/tut_gobject.xml @@ -294,7 +294,7 @@ ViewerFile *file = g_object_new (VIEWER_TYPE_FILE, NULL); memory will be freed or returned to the object pool for this type. Once the object has been freed, if it was the last instance of the type, the type's class will be destroyed as described in and - . + . diff --git a/docs/reference/gobject/tut_gtype.xml b/docs/reference/gobject/tut_gtype.xml index ee042889d..c2d51b9a5 100644 --- a/docs/reference/gobject/tut_gtype.xml +++ b/docs/reference/gobject/tut_gtype.xml @@ -599,7 +599,7 @@ B *b; interface initialization, see - + @@ -610,7 +610,7 @@ B *b; Last call to g_type_free_instance for target type interface destruction, see - + @@ -633,8 +633,8 @@ B *b; - - Non-instantiatable classed types: interfaces + + Non-instantiatable non-classed types: interfaces This section covers the theory behind interfaces. See @@ -649,7 +649,7 @@ B *b; be seen as a playback interface. Once you know what they do, you can control your CD player, MP3 player or anything that uses these symbols. To declare an interface you have to register a non-instantiatable - classed type which derives from + non-classed type which derives from GTypeInterface. The following piece of code declares such an interface. #define VIEWER_TYPE_EDITABLE viewer_editable_get_type () @@ -792,7 +792,7 @@ struct _GInterfaceInfo - + Interface Initialization @@ -937,7 +937,7 @@ viewer_editable_default_init (ViewerEditableInterface *iface) - + Interface Destruction @@ -955,7 +955,7 @@ viewer_editable_default_init (ViewerEditableInterface *iface) Again, it is important to understand, as in - , + , that both interface_finalize and base_finalize are invoked exactly once for the destruction of each implementation of an interface. Thus, if you were to use one of these functions, you would need to use a static integer variable diff --git a/docs/reference/gobject/tut_howto.xml b/docs/reference/gobject/tut_howto.xml index 4ed178cec..9bff49b56 100644 --- a/docs/reference/gobject/tut_howto.xml +++ b/docs/reference/gobject/tut_howto.xml @@ -854,7 +854,7 @@ b_method_to_call (B *obj, gint some_param) The theory behind how GObject interfaces work is given in - ; this section covers how to + ; this section covers how to define and implement an interface. diff --git a/gobject/gtype.h b/gobject/gtype.h index a555a90dd..b68af22ca 100644 --- a/gobject/gtype.h +++ b/gobject/gtype.h @@ -304,6 +304,15 @@ G_BEGIN_DECLS * * Checks if @type is a classed type. * + * A classed type has an associated #GTypeClass which can be derived to store + * class-wide virtual function pointers and data for all instances of the type. + * This allows for subclassing. All #GObjects are classed; none of the scalar + * fundamental types built into GLib are classed. + * + * Interfaces are not classed: while their #GTypeInterface struct could be + * considered similar to #GTypeClass, and classes can derive interfaces, + * #GTypeInterface doesn’t allow for subclassing. + * * Returns: %TRUE if @type is classed */ #define G_TYPE_IS_CLASSED(type) (g_type_test_flags ((type), G_TYPE_FLAG_CLASSED)) From d1eb9c840c11abdfd04185519249de7f55d3c783 Mon Sep 17 00:00:00 2001 From: Philip Withnall Date: Thu, 13 Apr 2023 15:39:37 +0100 Subject: [PATCH 3/3] tests: Add type flag tests for interfaces Signed-off-by: Philip Withnall Helps: #252 --- gobject/tests/type-flags.c | 37 +++++++++++++++++++++++++++++++++++++ 1 file changed, 37 insertions(+) diff --git a/gobject/tests/type-flags.c b/gobject/tests/type-flags.c index 653cb9b01..bb67f8c03 100644 --- a/gobject/tests/type-flags.c +++ b/gobject/tests/type-flags.c @@ -3,6 +3,42 @@ #include +typedef struct +{ + GTypeInterface g_iface; +} TestInterfaceInterface; + +GType test_interface_get_type (void); +#define TEST_TYPE_INTERFACE test_interface_get_type () +G_DEFINE_INTERFACE (TestInterface, test_interface, G_TYPE_INVALID) + +static void +test_interface_default_init (TestInterfaceInterface *iface) +{ +} + +static void +test_type_flags_interface (void) +{ + g_assert_false (G_TYPE_IS_ABSTRACT (TEST_TYPE_INTERFACE)); + g_assert_false (g_type_test_flags (TEST_TYPE_INTERFACE, G_TYPE_FLAG_ABSTRACT)); + + g_assert_false (G_TYPE_IS_CLASSED (TEST_TYPE_INTERFACE)); + g_assert_false (g_type_test_flags (TEST_TYPE_INTERFACE, G_TYPE_FLAG_CLASSED)); + + g_assert_false (G_TYPE_IS_DEEP_DERIVABLE (TEST_TYPE_INTERFACE)); + g_assert_false (g_type_test_flags (TEST_TYPE_INTERFACE, G_TYPE_FLAG_DEEP_DERIVABLE)); + + g_assert_true (G_TYPE_IS_DERIVABLE (TEST_TYPE_INTERFACE)); + g_assert_true (g_type_test_flags (TEST_TYPE_INTERFACE, G_TYPE_FLAG_DERIVABLE)); + + g_assert_false (G_TYPE_IS_FINAL (TEST_TYPE_INTERFACE)); + g_assert_false (g_type_test_flags (TEST_TYPE_INTERFACE, G_TYPE_FLAG_FINAL)); + + g_assert_false (G_TYPE_IS_INSTANTIATABLE (TEST_TYPE_INTERFACE)); + g_assert_false (g_type_test_flags (TEST_TYPE_INTERFACE, G_TYPE_FLAG_INSTANTIATABLE)); +} + #define TEST_TYPE_FINAL (test_final_get_type()) G_DECLARE_FINAL_TYPE (TestFinal, test_final, TEST, FINAL, GObject) @@ -201,6 +237,7 @@ main (int argc, char *argv[]) g_setenv ("G_ENABLE_DIAGNOSTIC", "1", TRUE); + g_test_add_func ("/type/flags/interface", test_type_flags_interface); g_test_add_func ("/type/flags/final", test_type_flags_final); g_test_add_func ("/type/flags/final/instance-check", test_type_flags_final_instance_check); g_test_add_func ("/type/flags/deprecated", test_type_flags_deprecated);