[glib] gparamspecs: Recommend use of most specific GParamSpec types

[Philip Withnall <pwithnall src gnome org>]

commit c639b628ec425ac28b79bd48c703fc7115b1fc97
Author: Philip Withnall <philip withnall collabora co uk>
Date:   Thu Dec 18 11:23:05 2014 +0000

    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

 gobject/gparamspecs.c |    7 ++++++-
 1 files changed, 6 insertions(+), 1 deletions(-)
---
diff --git a/gobject/gparamspecs.c b/gobject/gparamspecs.c
index c48ae0c..b299b2a 100644
--- 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.
  *