From: Philip Withnall Date: Thu, 18 Dec 2014 11:23:05 +0000 (+0000) Subject: gparamspecs: Recommend use of most specific GParamSpec types X-Git-Tag: 2.43.92~52 X-Git-Url: http://review.tizen.org/git/?a=commitdiff_plain;h=c639b628ec425ac28b79bd48c703fc7115b1fc97;p=platform%2Fupstream%2Fglib.git 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 --- 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. *