[gtksourceview/wip/search] search: more API documentation

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

commit 8f6410ebdcf8197ca231322db8a9d814d91f7b19
Author: Sébastien Wilmet <swilmet gnome org>
Date:   Sat Jul 6 23:01:22 2013 +0200

    search: more API documentation

 gtksourceview/gtksourcebuffer.c |  107 ++++++++++++++++++++++++++++++++++++++-
 gtksourceview/gtksourceutils.c  |    2 +
 2 files changed, 107 insertions(+), 2 deletions(-)
---
diff --git a/gtksourceview/gtksourcebuffer.c b/gtksourceview/gtksourcebuffer.c
index f37aa7b..a89c68e 100644
--- a/gtksourceview/gtksourcebuffer.c
+++ b/gtksourceview/gtksourcebuffer.c
@@ -2672,6 +2672,15 @@ gtk_source_buffer_get_search_text (GtkSourceBuffer *buffer)
        return _gtk_source_search_get_text (buffer->priv->search);
 }
 
+/**
+ * gtk_source_buffer_set_case_sensitive_search:
+ * @buffer: a #GtkSourceBuffer.
+ * @case_sensitive: the setting.
+ *
+ * Enables or disables the case sensitivity for the search.
+ *
+ * Since: 3.10
+ */
 void
 gtk_source_buffer_set_case_sensitive_search (GtkSourceBuffer *buffer,
                                             gboolean         case_sensitive)
@@ -2693,6 +2702,13 @@ gtk_source_buffer_set_case_sensitive_search (GtkSourceBuffer *buffer,
        }
 }
 
+/**
+ * gtk_source_buffer_get_case_sensitive_search:
+ * @buffer: a #GtkSourceBuffer.
+ *
+ * Returns: whether the search is case sensitive.
+ * Since: 3.10
+ */
 gboolean
 gtk_source_buffer_get_case_sensitive_search (GtkSourceBuffer *buffer)
 {
@@ -2701,6 +2717,18 @@ gtk_source_buffer_get_case_sensitive_search (GtkSourceBuffer *buffer)
        return _gtk_source_search_get_case_sensitive (buffer->priv->search);
 }
 
+/**
+ * gtk_source_buffer_set_search_at_word_boundaries:
+ * @buffer: a #GtkSourceBuffer.
+ * @at_word_boundaries: the setting.
+ *
+ * Change whether the search is done at word boundaries. If @at_word_boundaries
+ * is %TRUE, a search match must start and end a word. The match can span
+ * multiple words. See also gtk_text_iter_starts_word() and
+ * gtk_text_iter_ends_word().
+ *
+ * Since: 3.10
+ */
 void
 gtk_source_buffer_set_search_at_word_boundaries (GtkSourceBuffer *buffer,
                                                 gboolean         at_word_boundaries)
@@ -2722,6 +2750,13 @@ gtk_source_buffer_set_search_at_word_boundaries (GtkSourceBuffer *buffer,
        }
 }
 
+/**
+ * gtk_source_buffer_get_search_at_word_boundaries:
+ * @buffer: a #GtkSourceBuffer.
+ *
+ * Returns: whether to search at word boundaries.
+ * Since: 3.10
+ */
 gboolean
 gtk_source_buffer_get_search_at_word_boundaries (GtkSourceBuffer *buffer)
 {
@@ -2730,6 +2765,18 @@ gtk_source_buffer_get_search_at_word_boundaries (GtkSourceBuffer *buffer)
        return _gtk_source_search_get_at_word_boundaries (buffer->priv->search);
 }
 
+/**
+ * gtk_source_buffer_set_search_wrap_around:
+ * @buffer: a #GtkSourceBuffer.
+ * @wrap_around: the setting.
+ *
+ * Enables or disables the wrap around search. If @wrap_around is %TRUE, the
+ * forward search continues at the beginning of the buffer if no search
+ * occurrences are found. Similarly, the backward search continues to search at
+ * the end of the buffer.
+ *
+ * Since: 3.10
+ */
 void
 gtk_source_buffer_set_search_wrap_around (GtkSourceBuffer *buffer,
                                          gboolean         wrap_around)
@@ -2751,6 +2798,13 @@ gtk_source_buffer_set_search_wrap_around (GtkSourceBuffer *buffer,
        }
 }
 
+/**
+ * gtk_source_buffer_get_search_wrap_around:
+ * @buffer: a #GtkSourceBuffer.
+ *
+ * Returns: whether to wrap around the search.
+ * Since: 3.10
+ */
 gboolean
 gtk_source_buffer_get_search_wrap_around (GtkSourceBuffer *buffer)
 {
@@ -2789,6 +2843,8 @@ gtk_source_buffer_get_search_occurrences_count (GtkSourceBuffer *buffer)
  * Returns: the position of the search occurrence. The first occurrence has the
  * position 1 (not 0). Returns 0 if @match_start and @match_end doesn't delimit
  * an occurrence. Returns -1 if the position is not yet known.
+ *
+ * Since: 3.10
  */
 gint
 gtk_source_buffer_get_search_occurrence_position (GtkSourceBuffer   *buffer,
@@ -2814,7 +2870,6 @@ gtk_source_buffer_get_search_occurrence_position (GtkSourceBuffer   *buffer,
  * Synchronous forward search.
  *
  * Returns: whether a match was found.
- *
  * Since: 3.10
  */
 gboolean
@@ -2840,7 +2895,8 @@ gtk_source_buffer_forward_search (GtkSourceBuffer   *buffer,
  * @callback: a #GAsyncReadyCallback to call when the operation is finished.
  * @user_data: the data to pass to the @callback function.
  *
- * Asynchronous forward search.
+ * Asynchronous forward search. See the #GAsyncResult documentation to know
+ * how to use this function.
  *
  * If the operation is cancelled, the @callback will only be called if
  * @cancellable was not %NULL. gtk_source_buffer_forward_search_async() takes
@@ -2865,6 +2921,20 @@ gtk_source_buffer_forward_search_async (GtkSourceBuffer     *buffer,
                                          user_data);
 }
 
+/**
+ * gtk_source_buffer_forward_search_finish:
+ * @buffer: a #GtkSourceBuffer.
+ * @result: a #GAsyncResult.
+ * @match_start: return location for start of match, or %NULL.
+ * @match_end: return location for end of match, or %NULL.
+ * @error: a #GError, or %NULL.
+ *
+ * Finishes a forward search started with
+ * gtk_source_buffer_forward_search_async().
+ *
+ * Returns: whether a match was found.
+ * Since: 3.10
+ */
 gboolean
 gtk_source_buffer_forward_search_finish (GtkSourceBuffer  *buffer,
                                         GAsyncResult     *result,
@@ -2891,6 +2961,7 @@ gtk_source_buffer_forward_search_finish (GtkSourceBuffer  *buffer,
  * Synchronous backward search.
  *
  * Returns: whether a match was found.
+ * Since: 3.10
  */
 gboolean
 gtk_source_buffer_backward_search (GtkSourceBuffer   *buffer,
@@ -2907,6 +2978,23 @@ gtk_source_buffer_backward_search (GtkSourceBuffer   *buffer,
                                            match_end);
 }
 
+/**
+ * gtk_source_buffer_backward_search_async:
+ * @buffer: a #GtkSourceBuffer.
+ * @iter: start of search.
+ * @cancellable: a #GCancellable, or %NULL.
+ * @callback: a #GAsyncReadyCallback to call when the operation is finished.
+ * @user_data: the data to pass to the @callback function.
+ *
+ * Asynchronous backward search. See the #GAsyncResult documentation to know
+ * how to use this function.
+ *
+ * If the operation is cancelled, the @callback will only be called if
+ * @cancellable was not %NULL. gtk_source_buffer_backward_search_async() takes
+ * ownership of @cancellable, so you can unref it after calling this function.
+ *
+ * Since: 3.10
+ */
 void
 gtk_source_buffer_backward_search_async (GtkSourceBuffer     *buffer,
                                         const GtkTextIter   *iter,
@@ -2924,6 +3012,20 @@ gtk_source_buffer_backward_search_async (GtkSourceBuffer     *buffer,
                                           user_data);
 }
 
+/**
+ * gtk_source_buffer_backward_search_finish:
+ * @buffer: a #GtkSourceBuffer.
+ * @result: a #GAsyncResult.
+ * @match_start: return location for start of match, or %NULL.
+ * @match_end: return location for end of match, or %NULL.
+ * @error: a #GError, or %NULL.
+ *
+ * Finishes a backward search started with
+ * gtk_source_buffer_backward_search_async().
+ *
+ * Returns: whether a match was found.
+ * Since: 3.10
+ */
 gboolean
 gtk_source_buffer_backward_search_finish (GtkSourceBuffer  *buffer,
                                          GAsyncResult     *result,
@@ -2982,6 +3084,7 @@ gtk_source_buffer_search_replace (GtkSourceBuffer   *buffer,
  * Replaces all search matches by another text.
  *
  * Returns: the number of replaced matches.
+ * Since: 3.10
  */
 guint
 gtk_source_buffer_search_replace_all (GtkSourceBuffer *buffer,
diff --git a/gtksourceview/gtksourceutils.c b/gtksourceview/gtksourceutils.c
index 3347dd1..c589031 100644
--- a/gtksourceview/gtksourceutils.c
+++ b/gtksourceview/gtksourceutils.c
@@ -41,6 +41,7 @@
  *
  * See also: gtk_source_utils_escape_search_text().
  *
+ * Returns: the unescaped @text.
  * Since: 3.10
  */
 gchar *
@@ -128,6 +129,7 @@ gtk_source_utils_unescape_search_text (const gchar *text)
  *
  * See also: gtk_source_utils_unescape_search_text().
  *
+ * Returns: the escaped @text.
  * Since: 3.10
  */
 gchar *