[gtksourceview/wip/regex-search: 11/16] Update API documentation for the regex search

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

commit 3145e1d880b02c4c831c231684737cdbfe7c98f9
Author: Sébastien Wilmet <swilmet gnome org>
Date:   Sun Jul 21 18:35:04 2013 +0200

    Update API documentation for the regex search

 docs/reference/gtksourceview-3.0-sections.txt |    1 +
 gtksourceview/gtksourcebuffer.c               |   33 +++++++++++++++++++------
 2 files changed, 26 insertions(+), 8 deletions(-)
---
diff --git a/docs/reference/gtksourceview-3.0-sections.txt b/docs/reference/gtksourceview-3.0-sections.txt
index a6dfc7c..f30fb49 100644
--- a/docs/reference/gtksourceview-3.0-sections.txt
+++ b/docs/reference/gtksourceview-3.0-sections.txt
@@ -48,6 +48,7 @@ gtk_source_buffer_set_search_wrap_around
 gtk_source_buffer_get_search_wrap_around
 gtk_source_buffer_set_regex_search
 gtk_source_buffer_get_regex_search
+gtk_source_buffer_get_regex_search_error
 gtk_source_buffer_set_highlight_search
 gtk_source_buffer_get_highlight_search
 gtk_source_buffer_get_search_occurrences_count
diff --git a/gtksourceview/gtksourcebuffer.c b/gtksourceview/gtksourcebuffer.c
index 9fbefb5..073e253 100644
--- a/gtksourceview/gtksourcebuffer.c
+++ b/gtksourceview/gtksourcebuffer.c
@@ -101,8 +101,9 @@
  *   <para>
  *     You can tune the search with the following properties:
  *     #GtkSourceBuffer:case-sensitive-search,
- *     #GtkSourceBuffer:search-at-word-boundaries and
- *     #GtkSourceBuffer:search-wrap-around.
+ *     #GtkSourceBuffer:search-at-word-boundaries,
+ *     #GtkSourceBuffer:search-wrap-around and
+ *     #GtkSourceBuffer:regex-search.
  *   </para>
  *   <para>
  *     To search forward, use gtk_source_buffer_forward_search() or
@@ -407,7 +408,9 @@ gtk_source_buffer_class_init (GtkSourceBufferClass *klass)
        /**
         * GtkSourceBuffer:search-text:
         *
-        * A search string, or %NULL if the search is disabled.
+        * A search string, or %NULL if the search is disabled. If the regular
+        * expression search is enabled, #GtkSourceBuffer:search-text is the
+        * pattern.
         *
         * Since: 3.10
         */
@@ -489,7 +492,8 @@ gtk_source_buffer_class_init (GtkSourceBufferClass *klass)
        /**
         * GtkSourceBuffer:regex-search:
         *
-        * Search by regular expression.
+        * Search by regular expressions with #GtkSourceBuffer:search-text as
+        * the pattern.
         *
         * Since: 3.10
         */
@@ -506,7 +510,7 @@ gtk_source_buffer_class_init (GtkSourceBufferClass *klass)
         *
         * If the regex search pattern doesn't follow all the rules,
         * #GtkSourceBuffer:regex-search-error will be set. If the pattern
-        * doesn't have errors, #GtkSourceBuffer:regex-search-error is %NULL.
+        * is valid, #GtkSourceBuffer:regex-search-error is %NULL.
         *
         * Free with g_error_free().
         *
@@ -2930,7 +2934,11 @@ gtk_source_buffer_get_search_wrap_around (GtkSourceBuffer *buffer)
  * @buffer: a #GtkSourceBuffer.
  * @regex: the setting.
  *
- * Enables or disables the regular expression search.
+ * Enables or disables whether to search by regular expressions.
+ * If enabled, the #GtkSourceBuffer:search-text property contains the pattern of
+ * the regular expression.
+ *
+ * See also gtk_source_buffer_get_regex_search_error().
  *
  * Since: 3.10
  */
@@ -2958,7 +2966,7 @@ gtk_source_buffer_set_regex_search (GtkSourceBuffer *buffer,
  * gtk_source_buffer_get_regex_search:
  * @buffer: a #GtkSourceBuffer.
  *
- * Returns: whether to search by regular expression.
+ * Returns: whether to search by regular expressions.
  * Since: 3.10
  */
 gboolean
@@ -2979,7 +2987,8 @@ gtk_source_buffer_get_regex_search (GtkSourceBuffer *buffer)
  *
  * Free the return value with g_error_free().
  *
- * Returns: the #GError, or %NULL.
+ * Returns: the #GError, or %NULL if the pattern is valid.
+ * Since: 3.10
  */
 GError *
 gtk_source_buffer_get_regex_search_error (GtkSourceBuffer *buffer)
@@ -3280,6 +3289,10 @@ gtk_source_buffer_backward_search_finish (GtkSourceBuffer  *buffer,
  * Replaces a search match by another text. If @match_start and @match_end
  * doesn't correspond to a search match, %FALSE is returned.
  *
+ * For a regular expression replacement, you can check if @replace is valid by
+ * calling g_regex_check_replacement(). The @replace text can contain
+ * backreferences; read the g_regex_replace() documentation for more details.
+ *
  * Returns: whether the match has been replaced.
  * Since: 3.10
  */
@@ -3311,6 +3324,10 @@ gtk_source_buffer_search_replace (GtkSourceBuffer   *buffer,
  * Replaces all search matches by another text. It is a synchronous function, so
  * it can block the user interface.
  *
+ * For a regular expression replacement, you can check if @replace is valid by
+ * calling g_regex_check_replacement(). The @replace text can contain
+ * backreferences; read the g_regex_replace() documentation for more details.
+ *
  * Returns: the number of replaced matches.
  * Since: 3.10
  */