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 090cb50..c0deac4 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 afccc21..ceb5803 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 2ab2c3e..90c5f7e 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.