Expand GObject::notify documentation. (#381722, Nickolay V. Shmyrev)

2006-12-17  Matthias Clasen  <mclasen@redhat.com>

        * gobject/tmpl/objects.sgml: Expand GObject::notify
        documentation.  (#381722, Nickolay V. Shmyrev)

        * gobject/tmpl/gparamspec.sgml: Add canonical-parameter-name id.

diff --git a/docs/reference/ChangeLog b/docs/reference/ChangeLog
index 090cb50d0bad12a455156be928aa3de27cf88ec2..c0deac4dcf938a826202b496880bceb329095d1b 100644 (file)
--- a/docs/reference/ChangeLog
+++ b/docs/reference/ChangeLog
@@ -1,3 +1,10 @@
+2006-12-17  Matthias Clasen  <mclasen@redhat.com>
+
+       * gobject/tmpl/objects.sgml: Expand GObject::notify
+       documentation.  (#381722, Nickolay V. Shmyrev)
+
+       * gobject/tmpl/gparamspec.sgml: Add canonical-parameter-name id.
+
 2006-12-15  Matthias Clasen  <mclasen@redhat.com>
 
        * glib/glib-docs.sgml: Add a "Since 2.14" section.

diff --git a/docs/reference/gobject/tmpl/gparamspec.sgml b/docs/reference/gobject/tmpl/gparamspec.sgml
index afccc212dbff68c733563c7a67d1831dd42596ca..ceb5803f989cf8cf73e23ea9755e5bdade3dcc4c 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 ##### -->

diff --git a/docs/reference/gobject/tmpl/objects.sgml b/docs/reference/gobject/tmpl/objects.sgml
index 2ab2c3e88edf941b777805cfa23152bea79b8cca..90c5f7e5bcb7f99b5199a45d33e5a7ee71a5f379 100644 (file)
--- a/docs/reference/gobject/tmpl/objects.sgml
+++ b/docs/reference/gobject/tmpl/objects.sgml
@@ -85,6 +85,19 @@ has been changed. Note that getting this signal doesn't guarantee that the
 value of the property has actually changed, it may also be emitted when
 the setter for the property is called to reinstate the previous value.
 </para>
+<para>
+This signal is typically used to obtain change notification for a 
+single property, by specifying the property name as a detail in the
+g_signal_connect() call, like this:
+<informalexample><programlisting>
+g_signal_connect (text_view->buffer, "notify::paste-target-list",
+                  G_CALLBACK (gtk_text_view_target_list_notify),
+                  text_view)
+</programlisting></informalexample>
+It is important to note that you must use 
+<link linkend="canonical-parameter-name">canonical</link> parameter names as
+detail strings for the notify signal.
+</para>
 
 @pspec: the #GParamSpec of the property which changed
 @gobject: the object which received the signal.