[glib: 1/2] docs: Clarify handling of 64-bit integer literals with g_object_new()

[Emmanuele Bassi <ebassi src gnome org>]

commit 2474c65037db4fa520ce05eb2087c64501997dcd
Author: Philip Withnall <withnall endlessm com>
Date:   Tue Dec 17 11:56:35 2019 +0000

    docs: Clarify handling of 64-bit integer literals with g_object_new()
    
    As with `g_variant_new()` (or any varargs function which takes integer
    literals of differing widths), callers need to be careful to ensure
    their integer literals have the right width.
    
    Tweak the documentation for `g_object_new()`, `g_object_set()` and
    `g_object_get()` to clarify this. The documentation for `g_object_get()`
    shows that it is not subject to the same caveats, since it operates on
    pointers.
    
    Signed-off-by: Philip Withnall <withnall endlessm com>
    
    Closes: #833

 gobject/gobject.c | 25 +++++++++++++++++++++++--
 1 file changed, 23 insertions(+), 2 deletions(-)
---
diff --git a/gobject/gobject.c b/gobject/gobject.c
index acb365a82..eea40b3ae 100644
--- a/gobject/gobject.c
+++ b/gobject/gobject.c
@@ -1747,6 +1747,20 @@ g_object_get_type (void)
  * Construction parameters (see #G_PARAM_CONSTRUCT, #G_PARAM_CONSTRUCT_ONLY)
  * which are not explicitly specified are set to their default values.
  *
+ * Note that in C, small integer types in variable argument lists are promoted
+ * up to #gint or #guint as appropriate, and read back accordingly. #gint is 32
+ * bits on every platform on which GLib is currently supported. This means that
+ * you can use C expressions of type #gint with g_object_new() and properties of
+ * type #gint or #guint or smaller. Specifically, you can use integer literals
+ * with these property types.
+ *
+ * When using property types of #gint64 or #guint64, you must ensure that the
+ * value that you provide is 64 bit. This means that you should use a cast or
+ * make use of the %G_GINT64_CONSTANT or %G_GUINT64_CONSTANT macros.
+ *
+ * Similarly, #gfloat is promoted to #gdouble, so you must ensure that the value
+ * you provide is a #gdouble, even for a property of type #gfloat.
+ *
  * Returns: (transfer full) (type GObject.Object): a new instance of
  *   @object_type
  */
@@ -2575,6 +2589,11 @@ g_object_get_valist (GObject      *object,
  *
  * Sets properties on an object.
  *
+ * The same caveats about passing integer literals as varargs apply as with
+ * g_object_new(). In particular, any integer literals set as the values for
+ * properties of type #gint64 or #guint64 must be 64 bits wide, using the
+ * %G_GINT64_CONSTANT or %G_GUINT64_CONSTANT macros.
+ *
  * Note that the "notify" signals are queued and only emitted (in
  * reverse order) after all properties have been set. See
  * g_object_freeze_notify().
@@ -2611,20 +2630,22 @@ g_object_set (gpointer     _object,
  * of three properties: an integer, a string and an object:
  * |[<!-- language="C" --> 
  *  gint intval;
+ *  guint64 uint64val;
  *  gchar *strval;
  *  GObject *objval;
  *
  *  g_object_get (my_object,
  *                "int-property", &intval,
+ *                "uint64-property", &uint64val,
  *                "str-property", &strval,
  *                "obj-property", &objval,
  *                NULL);
  *
- *  // Do something with intval, strval, objval
+ *  // Do something with intval, uint64val, strval, objval
  *
  *  g_free (strval);
  *  g_object_unref (objval);
- *  ]|
+ * ]|
  */
 void
 g_object_get (gpointer     _object,