[glib: 1/3] docs: Use G_PARAM_STATIC_STRINGS in examples and explain it more

[Philip Withnall <pwithnall src gnome org>]

commit 8f9c5090db695c1b83e90bdcf86013d8a30b5b81
Author: Philip Withnall <pwithnall endlessos org>
Date:   Fri May 20 12:55:18 2022 +0100

    docs: Use G_PARAM_STATIC_STRINGS in examples and explain it more
    
    Make it a bit clearer in the documentation that using
    `G_PARAM_STATIC_STRINGS` everywhere is a good thing.
    
    Signed-off-by: Philip Withnall <pwithnall endlessos org>

 docs/reference/gobject/tut_gobject.xml | 4 ++--
 docs/reference/gobject/tut_howto.xml   | 2 +-
 gobject/glib-types.h                   | 2 +-
 gobject/gobject.c                      | 6 +++---
 gobject/gparam.h                       | 6 ++++++
 5 files changed, 13 insertions(+), 7 deletions(-)
---
diff --git a/docs/reference/gobject/tut_gobject.xml b/docs/reference/gobject/tut_gobject.xml
index 0423a38a30..7a2ecc77e7 100644
--- a/docs/reference/gobject/tut_gobject.xml
+++ b/docs/reference/gobject/tut_gobject.xml
@@ -555,7 +555,7 @@ viewer_file_class_init (ViewerFileClass *klass)
                          "Filename",
                          "Name of the file to load and display from.",
                          NULL  /* default value */,
-                         G_PARAM_CONSTRUCT_ONLY | G_PARAM_READWRITE);
+                         G_PARAM_CONSTRUCT_ONLY | G_PARAM_READWRITE | G_PARAM_STATIC_STRINGS);
 
   obj_properties[PROP_ZOOM_LEVEL] =
     g_param_spec_uint ("zoom-level",
@@ -564,7 +564,7 @@ viewer_file_class_init (ViewerFileClass *klass)
                        0  /* minimum value */,
                        10 /* maximum value */,
                        2  /* default value */,
-                       G_PARAM_READWRITE);
+                       G_PARAM_READWRITE | G_PARAM_STATIC_STRINGS);
 
   g_object_class_install_properties (object_class,
                                      N_PROPERTIES,
diff --git a/docs/reference/gobject/tut_howto.xml b/docs/reference/gobject/tut_howto.xml
index b61a328b6e..4ed178cec6 100644
--- a/docs/reference/gobject/tut_howto.xml
+++ b/docs/reference/gobject/tut_howto.xml
@@ -1226,7 +1226,7 @@ viewer_editable_default_init (ViewerEditableInterface *iface)
                                                             0.0,  /* minimum */
                                                             G_MAXDOUBLE,  /* maximum */
                                                             0.0,  /* default */
-                                                            G_PARAM_READWRITE));
+                                                            G_PARAM_READWRITE | G_PARAM_STATIC_STRINGS));
 }
 </programlisting></informalexample>
     </para>
diff --git a/gobject/glib-types.h b/gobject/glib-types.h
index f0d33234a1..c54eda99cd 100644
--- a/gobject/glib-types.h
+++ b/gobject/glib-types.h
@@ -54,7 +54,7 @@ typedef gsize GType;
  *                                                      _("Authors"),
  *                                                      _("List of authors"),
  *                                                      G_TYPE_STRV,
- *                                                      G_PARAM_READWRITE));
+ *                                                      G_PARAM_READWRITE | G_PARAM_STATIC_STRINGS));
  *
  * gchar *authors[] = { "Owen", "Tim", NULL };
  * g_object_set (obj, "authors", authors, NULL);
diff --git a/gobject/gobject.c b/gobject/gobject.c
index d33d8e5b04..caee34f4e3 100644
--- a/gobject/gobject.c
+++ b/gobject/gobject.c
@@ -722,12 +722,12 @@ g_object_class_install_property (GObjectClass *class,
  *     g_param_spec_int ("foo", "Foo", "Foo",
  *                       -1, G_MAXINT,
  *                       0,
- *                       G_PARAM_READWRITE);
+ *                       G_PARAM_READWRITE | G_PARAM_STATIC_STRINGS);
  *
  *   obj_properties[PROP_BAR] =
  *     g_param_spec_string ("bar", "Bar", "Bar",
  *                          NULL,
- *                          G_PARAM_READWRITE);
+ *                          G_PARAM_READWRITE | G_PARAM_STATIC_STRINGS);
  *
  *   gobject_class->set_property = my_object_set_property;
  *   gobject_class->get_property = my_object_get_property;
@@ -1421,7 +1421,7 @@ g_object_notify (GObject     *object,
  *     properties[PROP_FOO] = g_param_spec_int ("foo", "Foo", "The foo",
  *                                              0, 100,
  *                                              50,
- *                                              G_PARAM_READWRITE);
+ *                                              G_PARAM_READWRITE | G_PARAM_STATIC_STRINGS);
  *     g_object_class_install_property (gobject_class,
  *                                      PROP_FOO,
  *                                      properties[PROP_FOO]);
diff --git a/gobject/gparam.h b/gobject/gparam.h
index e0f316682d..4dff763e5e 100644
--- a/gobject/gparam.h
+++ b/gobject/gparam.h
@@ -172,6 +172,12 @@ typedef enum
  * 
  * #GParamFlags value alias for %G_PARAM_STATIC_NAME | %G_PARAM_STATIC_NICK | %G_PARAM_STATIC_BLURB.
  * 
+ * It is recommended to use this for all properties by default, as it allows for
+ * internal performance improvements in GObject.
+ *
+ * It is very rare that a property would have a dynamically constructed name,
+ * nickname or blurb.
+ *
  * Since 2.13.0
  */
 #define        G_PARAM_STATIC_STRINGS (G_PARAM_STATIC_NAME | G_PARAM_STATIC_NICK | G_PARAM_STATIC_BLURB)