From c639b628ec425ac28b79bd48c703fc7115b1fc97 Mon Sep 17 00:00:00 2001 From: Philip Withnall Date: Thu, 18 Dec 2014 11:23:05 +0000 Subject: [PATCH] gparamspecs: Recommend use of most specific GParamSpec types MIME-Version: 1.0 Content-Type: text/plain; charset=utf8 Content-Transfer-Encoding: 8bit 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 file changed, 6 insertions(+), 1 deletion(-) 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. * -- 2.7.4