mirror of
https://gitlab.gnome.org/GNOME/glib.git
synced 2024-12-24 14:36:13 +01:00
gobject: Document behaviour of GType checking macros on NULL
The macros differ in their handling of NULL values — some macros ignore them and pass through (e.g. G_TYPE_CHECK_INSTANCE_CAST) while others will explicitly emit a warning if passed NULL (e.g. G_TYPE_CHECK_INSTANCE). Document their behaviour, so people don’t end up putting unnecessary NULL checks in their code when doing checked type casts. https://bugzilla.gnome.org/show_bug.cgi?id=735731
This commit is contained in:
parent
c8330b80fc
commit
953c182d25
@ -457,7 +457,8 @@ struct _GTypeQuery
|
||||
* @instance: Location of a #GTypeInstance structure
|
||||
*
|
||||
* Checks if @instance is a valid #GTypeInstance structure,
|
||||
* otherwise issues a warning and returns %FALSE.
|
||||
* otherwise issues a warning and returns %FALSE. %NULL is not a valid
|
||||
* #GTypeInstance.
|
||||
*
|
||||
* This macro should only be used in type implementations.
|
||||
*
|
||||
@ -466,7 +467,7 @@ struct _GTypeQuery
|
||||
#define G_TYPE_CHECK_INSTANCE(instance) (_G_TYPE_CHI ((GTypeInstance*) (instance)))
|
||||
/**
|
||||
* G_TYPE_CHECK_INSTANCE_CAST:
|
||||
* @instance: Location of a #GTypeInstance structure
|
||||
* @instance: (nullable): Location of a #GTypeInstance structure
|
||||
* @g_type: The type to be returned
|
||||
* @c_type: The corresponding C type of @g_type
|
||||
*
|
||||
@ -474,15 +475,18 @@ struct _GTypeQuery
|
||||
* and issues a warning if this is not the case. Returns @instance casted
|
||||
* to a pointer to @c_type.
|
||||
*
|
||||
* No warning will be issued if @instance is %NULL, and %NULL will be returned.
|
||||
*
|
||||
* This macro should only be used in type implementations.
|
||||
*/
|
||||
#define G_TYPE_CHECK_INSTANCE_CAST(instance, g_type, c_type) (_G_TYPE_CIC ((instance), (g_type), c_type))
|
||||
/**
|
||||
* G_TYPE_CHECK_INSTANCE_TYPE:
|
||||
* @instance: Location of a #GTypeInstance structure.
|
||||
* @instance: (nullable): Location of a #GTypeInstance structure.
|
||||
* @g_type: The type to be checked
|
||||
*
|
||||
* Checks if @instance is an instance of the type identified by @g_type.
|
||||
* Checks if @instance is an instance of the type identified by @g_type. If
|
||||
* @instance is %NULL, %FALSE will be returned.
|
||||
*
|
||||
* This macro should only be used in type implementations.
|
||||
*
|
||||
@ -491,10 +495,11 @@ struct _GTypeQuery
|
||||
#define G_TYPE_CHECK_INSTANCE_TYPE(instance, g_type) (_G_TYPE_CIT ((instance), (g_type)))
|
||||
/**
|
||||
* G_TYPE_CHECK_INSTANCE_FUNDAMENTAL_TYPE:
|
||||
* @instance: Location of a #GTypeInstance structure.
|
||||
* @instance: (nullable): Location of a #GTypeInstance structure.
|
||||
* @g_type: The fundamental type to be checked
|
||||
*
|
||||
* Checks if @instance is an instance of the fundamental type identified by @g_type.
|
||||
* If @instance is %NULL, %FALSE will be returned.
|
||||
*
|
||||
* This macro should only be used in type implementations.
|
||||
*
|
||||
@ -539,18 +544,18 @@ struct _GTypeQuery
|
||||
*
|
||||
* Checks that @g_class is a class structure of the type identified by @g_type
|
||||
* and issues a warning if this is not the case. Returns @g_class casted
|
||||
* to a pointer to @c_type.
|
||||
* to a pointer to @c_type. %NULL is not a valid class structure.
|
||||
*
|
||||
* This macro should only be used in type implementations.
|
||||
*/
|
||||
#define G_TYPE_CHECK_CLASS_CAST(g_class, g_type, c_type) (_G_TYPE_CCC ((g_class), (g_type), c_type))
|
||||
/**
|
||||
* G_TYPE_CHECK_CLASS_TYPE:
|
||||
* @g_class: Location of a #GTypeClass structure
|
||||
* @g_class: (nullable): Location of a #GTypeClass structure
|
||||
* @g_type: The type to be checked
|
||||
*
|
||||
* Checks if @g_class is a class structure of the type identified by
|
||||
* @g_type.
|
||||
* @g_type. If @g_class is %NULL, %FALSE will be returned.
|
||||
*
|
||||
* This macro should only be used in type implementations.
|
||||
*
|
||||
|
Loading…
Reference in New Issue
Block a user