2.17.1

[platform/upstream/glib.git] / docs / reference / gobject / tmpl / gparamspec.sgml

diff --git a/docs/reference/gobject/tmpl/gparamspec.sgml b/docs/reference/gobject/tmpl/gparamspec.sgml
index 75399b8..cebf58e 100644 (file)
--- a/docs/reference/gobject/tmpl/gparamspec.sgml
+++ b/docs/reference/gobject/tmpl/gparamspec.sgml
@@ -9,10 +9,12 @@ Metadata for parameter specifications
 #GParamSpec is an object structure that encapsulates the metadata
 required to specify parameters, such as e.g. #GObject properties.
 </para>
-<para>
+<para id="canonical-parameter-name">
 Parameter names need to start with a letter (a-z or A-Z). Subsequent
 characters can be letters, numbers or a '-'.
 All other characters are replaced by a '-' during construction.
+The result of this replacement is called the canonical name of the
+parameter.
 </para>
 
 <!-- ##### SECTION See_Also ##### -->
@@ -147,6 +149,11 @@ can be configured.
                          parameter is guaranteed to remain valid and
                          unmodified for the lifetime of the parameter. 
                          Since 2.8
+@G_PARAM_PRIVATE: 
+@G_PARAM_STATIC_NICK:    the string used as nick when constructing the
+                         parameter is guaranteed to remain valid and
+                         unmmodified for the lifetime of the parameter.
+                         Since 2.8
 @G_PARAM_STATIC_BLURB:   the string used as blurb when constructing the 
                          parameter is guaranteed to remain valid and 
                          unmodified for the lifetime of the parameter. 
@@ -159,6 +166,15 @@ can be configured.
 
 
 
+<!-- ##### MACRO G_PARAM_STATIC_STRINGS ##### -->
+<para>
+#GParamFlags value alias for %G_PARAM_STATIC_NAME | %G_PARAM_STATIC_NICK | %G_PARAM_STATIC_BLURB.
+
+Since 2.13.0
+</para>
+
+
+
 <!-- ##### MACRO G_PARAM_MASK ##### -->
 <para>
 Mask containing the bits of #GParamSpec.flags which are reserved for GLib.
@@ -205,6 +221,16 @@ not flagged "floating" anymore).
 @pspec: a valid #GParamSpec
 
 
+<!-- ##### FUNCTION g_param_spec_ref_sink ##### -->
+<para>
+Convenience function to ref and sink a #GParamSpec.
+</para>
+
+@pspec: a valid #GParamSpec
+@Returns: the #GParamSpec that was passed into this function
+@Since: 2.10
+
+
 <!-- ##### FUNCTION g_param_value_set_default ##### -->
 <para>
 Sets @value to its default value as specified in @pspec.
@@ -221,7 +247,7 @@ Checks whether @value contains the default value as specified in @pspec.
 
 @pspec:   a valid #GParamSpec
 @value:   a #GValue of correct type for @pspec
-@Returns: whether @value contains the canonical defualt for this @pspec
+@Returns: whether @value contains the canonical default for this @pspec
 
 
 <!-- ##### FUNCTION g_param_value_validate ##### -->
@@ -360,7 +386,7 @@ returns that paramspec. Redirect is used typically for
 providing a new implementation of a property in a derived
 type while preserving all the properties from the parent
 type. Redirection is established by creating a property
-of type #GParamSpecOverride. See g_object_override_property()
+of type #GParamSpecOverride. See g_object_class_override_property()
 for an example of the use of this capability.
 </para>
 
@@ -385,6 +411,13 @@ When creating and looking up a #GParamSpec, either separator can be used,
 but they cannot be mixed. Using '-' is considerably more efficient and in 
 fact required when using property names as detail strings for signals.
 </para>
+<para>
+Beyond the name, #GParamSpec<!-- -->s have two more descriptive strings 
+associated with them, the @nick, which should be suitable for use as 
+a label for the property in a property editor, and the @blurb, which should
+be a somewhat longer description, suitable for e.g. a tooltip. The @nick
+and @blurb should ideally be localized.
+</para>
 
 @param_type: the #GType for the property; must be derived from #G_TYPE_PARAM
 @name: the canonical name of the property
@@ -406,7 +439,7 @@ g_param_type_register_static().
 </para>
 
 @instance_size: Size of the instance (object) structure.
-@n_preallocs: Number of pre-allocated (cached) instances to reserve memory for (0 indicates no caching).
+@n_preallocs: Prior to GLib 2.10, it specified the number of pre-allocated (cached) instances to reserve memory for (0 indicates no caching). Since GLib 2.10, it is ignored, since instances are allocated with the <link linkend="glib-Memory-Slices">slice allocator</link> now.
 @instance_init: Location of the instance initialization function (optional).
 @value_type: The #GType of values conforming to this #GParamSpec
 @finalize: The instance finalization function (optional).