gparamspecs: Recommend use of most specific GParamSpec types

It’s quite common to see a g_param_spec_pointer() used for GObject or
boxed types which, while not incorrect, does make memory management
unsafe, since no copying or reference counting can be performed
automatically.

Similarly, people often use g_param_spec_boolean() when an enum would be
more appropriate, cf.
    http://blog.ometer.com/2011/01/20/boolean-parameters-are-wrong/
Using enums also means that the set of allowable values can be extended
in future if needed.

In the hope that people who write code like that read the documentation,
mention the more specific types in the documentation.

https://bugzilla.gnome.org/show_bug.cgi?id=741779

diff --git a/gobject/gparamspecs.c b/gobject/gparamspecs.c
index c48ae0c..b299b2a 100644 (file)
--- a/gobject/gparamspecs.c
+++ b/gobject/gparamspecs.c
@@ -1685,7 +1685,10 @@ g_param_spec_uchar (const gchar *name,
  * @flags: flags for the property specified
  *
  * Creates a new #GParamSpecBoolean instance specifying a %G_TYPE_BOOLEAN
- * property.
+ * property. In many cases, it may be more appropriate to use an enum with
+ * g_param_spec_enum(), both to improve code clarity by using explicitly named
+ * values, and to allow for more values to be added in future without breaking
+ * API.
  *
  * See g_param_spec_internal() for details on property names.
  *
@@ -2326,6 +2329,8 @@ g_param_spec_boxed (const gchar *name,
  * @flags: flags for the property specified
  *
  * Creates a new #GParamSpecPointer instance specifying a pointer property.
+ * Where possible, it is better to use g_param_spec_object() or
+ * g_param_spec_boxed() to expose memory management information.
  *
  * See g_param_spec_internal() for details on property names.
  *