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

1 files changed, 13 insertions, 8 deletions

diff --git a/gobject/gtype.h b/gobject/gtype.h
index b564bbb96..d010a31a8 100644
--- a/gobject/gtype.h
+++ b/gobject/gtype.h
@@ -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,23 +467,26 @@ 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
  * 
  * Checks that @instance is an instance of the type identified by @g_type
  * 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.
  *