[gtksourceview: 2/3] Bracket matching: improve doc

[Sébastien Wilmet <swilmet src gnome org>]

commit 9a5dabf2b058eedd5c6a32002c4c0e5f0b7ef770
Author: Sébastien Wilmet <swilmet gnome org>
Date:   Sat Oct 24 10:51:24 2015 +0200

    Bracket matching: improve doc

 gtksourceview/gtksourcebuffer.c |    9 +++++++--
 1 files changed, 7 insertions(+), 2 deletions(-)
---
diff --git a/gtksourceview/gtksourcebuffer.c b/gtksourceview/gtksourcebuffer.c
index 78e7626..f0a881f 100644
--- a/gtksourceview/gtksourcebuffer.c
+++ b/gtksourceview/gtksourcebuffer.c
@@ -467,13 +467,18 @@ gtk_source_buffer_class_init (GtkSourceBufferClass *klass)
        /**
         * GtkSourceBuffer::bracket-matched:
         * @buffer: a #GtkSourceBuffer.
-        * @iter: iterator to initialize.
-        * @state: state of bracket matching
+        * @iter: if found, the location of the matching bracket.
+        * @state: state of bracket matching.
         *
         * @iter is set to a valid iterator pointing to the matching bracket
         * if @state is %GTK_SOURCE_BRACKET_MATCH_FOUND. Otherwise @iter is
         * meaningless.
         *
+        * The signal is emitted only when the @state changes, typically when
+        * the cursor moves.
+        *
+        * A use-case for this signal is to show messages in a #GtkStatusbar.
+        *
         * Since: 2.12
         */
        buffer_signals[BRACKET_MATCHED] =