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

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

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

    search: more API documentation

 docs/reference/gtksourceview-3.0-sections.txt |   18 ++-
 gtksourceview/gtksourcebuffer.c               |  198 +++++++++++++++++++++----
 gtksourceview/gtksourceutils.c                |    2 +
 3 files changed, 182 insertions(+), 36 deletions(-)
---
diff --git a/docs/reference/gtksourceview-3.0-sections.txt b/docs/reference/gtksourceview-3.0-sections.txt
index a9565cd..a432ef3 100644
--- a/docs/reference/gtksourceview-3.0-sections.txt
+++ b/docs/reference/gtksourceview-3.0-sections.txt
@@ -15,14 +15,6 @@ gtk_source_buffer_set_highlight_matching_brackets
 gtk_source_buffer_get_highlight_matching_brackets
 gtk_source_buffer_set_style_scheme
 gtk_source_buffer_get_style_scheme
-gtk_source_buffer_get_max_undo_levels
-gtk_source_buffer_set_max_undo_levels
-gtk_source_buffer_redo
-gtk_source_buffer_undo
-gtk_source_buffer_can_redo
-gtk_source_buffer_can_undo
-gtk_source_buffer_begin_not_undoable_action
-gtk_source_buffer_end_not_undoable_action
 gtk_source_buffer_ensure_highlight
 gtk_source_buffer_create_source_mark
 gtk_source_buffer_forward_iter_to_source_mark
@@ -34,8 +26,18 @@ gtk_source_buffer_iter_has_context_class
 gtk_source_buffer_get_context_classes_at_iter
 gtk_source_buffer_iter_forward_to_context_class_toggle
 gtk_source_buffer_iter_backward_to_context_class_toggle
+<SUBSECTION>
+gtk_source_buffer_get_max_undo_levels
+gtk_source_buffer_set_max_undo_levels
+gtk_source_buffer_redo
+gtk_source_buffer_undo
+gtk_source_buffer_can_redo
+gtk_source_buffer_can_undo
+gtk_source_buffer_begin_not_undoable_action
+gtk_source_buffer_end_not_undoable_action
 gtk_source_buffer_get_undo_manager
 gtk_source_buffer_set_undo_manager
+<SUBSECTION>
 gtk_source_buffer_set_search_text
 gtk_source_buffer_get_search_text
 gtk_source_buffer_set_case_sensitive_search
diff --git a/gtksourceview/gtksourcebuffer.c b/gtksourceview/gtksourcebuffer.c
index f37aa7b..bea13a1 100644
--- a/gtksourceview/gtksourcebuffer.c
+++ b/gtksourceview/gtksourcebuffer.c
@@ -50,32 +50,71 @@
  * @Title: GtkSourceBuffer
  * @See_also: #GtkTextBuffer, #GtkSourceView
  *
- * The #GtkSourceBuffer object is the model for #GtkSourceView widgets.
- * It extends the #GtkTextBuffer object by adding features useful to display
- * and edit source code as syntax highlighting and bracket matching. It
- * also implements support for undo/redo operations.
- *
- * To create a #GtkSourceBuffer use gtk_source_buffer_new() or
- * gtk_source_buffer_new_with_language(). The second form is just a convenience
- * function which allows you to initially set a #GtkSourceLanguage.
- *
- * By default highlighting is enabled, but you can disable it with
- * gtk_source_buffer_set_highlight_syntax().
- *
- * A custom #GtkSourceUndoManager can be implemented and set with
- * gtk_source_buffer_set_undo_manager(). However the default implementation
- * should be suitable for most uses. By default, actions that can be undone or
- * redone are defined as groups of operations between a call to
- * gtk_text_buffer_begin_user_action() and gtk_text_buffer_end_user_action(). In
- * general, this happens whenever the user presses any key which modifies the
- * buffer. But the default undo manager will try to merge similar consecutive
- * actions, such as multiple character insertions on the same line, into one
- * action. But, inserting a newline starts a new action.
- *
- * The default undo manager remembers the "modified" state of the buffer, and
- * restore it when an action is undone or redone. It can be useful in a text
- * editor to know whether the file is saved. See gtk_text_buffer_get_modified()
- * and gtk_text_buffer_set_modified().
+ * <para>
+ *   The #GtkSourceBuffer object is the model for #GtkSourceView widgets.
+ *   It extends the #GtkTextBuffer object by adding features useful to display
+ *   and edit source code such as syntax highlighting and bracket matching. It
+ *   also implements support for undo/redo operations, and for the search and
+ *   replace.
+ * </para>
+ * <para>
+ *   To create a #GtkSourceBuffer use gtk_source_buffer_new() or
+ *   gtk_source_buffer_new_with_language(). The second form is just a convenience
+ *   function which allows you to initially set a #GtkSourceLanguage.
+ * </para>
+ * <para>
+ *   By default highlighting is enabled, but you can disable it with
+ *   gtk_source_buffer_set_highlight_syntax().
+ * </para>
+ * <refsect2>
+ *   <title>Undo and Redo</title>
+ *   <para>
+ *     A custom #GtkSourceUndoManager can be implemented and set with
+ *     gtk_source_buffer_set_undo_manager(). However the default implementation
+ *     should be suitable for most uses. By default, actions that can be undone or
+ *     redone are defined as groups of operations between a call to
+ *     gtk_text_buffer_begin_user_action() and gtk_text_buffer_end_user_action(). In
+ *     general, this happens whenever the user presses any key which modifies the
+ *     buffer. But the default undo manager will try to merge similar consecutive
+ *     actions, such as multiple character insertions on the same line, into one
+ *     action. But, inserting a newline starts a new action.
+ *   </para>
+ *   <para>
+ *     The default undo manager remembers the "modified" state of the buffer, and
+ *     restore it when an action is undone or redone. It can be useful in a text
+ *     editor to know whether the file is saved. See gtk_text_buffer_get_modified()
+ *     and gtk_text_buffer_set_modified().
+ *   </para>
+ * </refsect2>
+ * <refsect2>
+ *   <title>Search and Replace</title>
+ *   <para>
+ *     To set the text to search, use gtk_source_buffer_set_search_text(). The
+ *     search occurrences will be highlighted, and the total number of
+ *     occurrences can be retrieved with
+ *     gtk_source_buffer_get_search_occurrences_count(). The buffer is scanned
+ *     asynchronously, so it doesn't block the user interface. For each search,
+ *     the buffer is scanned at most once. After that, navigating through the
+ *     occurrences doesn't require to re-scan the buffer entirely.
+ *   </para>
+ *   <para>
+ *     You can tune the search with the following properties:
+ *     #GtkSourceBuffer:case-sensitive-search,
+ *     #GtkSourceBuffer:search-at-word-boundaries and
+ *     #GtkSourceBuffer:search-wrap-around.
+ *   </para>
+ *   <para>
+ *     To search forward, use gtk_source_buffer_forward_search() or
+ *     gtk_source_buffer_forward_search_async() for the asynchronous version.
+ *     The backward search is done similarly. To replace a search match, or all
+ *     matches, use gtk_source_buffer_search_replace() and
+ *     gtk_source_buffer_search_replace_all().
+ *   </para>
+ *   <para>
+ *     To know the position of a certain match, use
+ *     gtk_source_buffer_get_search_occurrence_position().
+ *   </para>
+ * </refsect2>
  */
 
 /*
@@ -2672,6 +2711,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 +2741,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 +2756,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 +2789,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 +2804,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 +2837,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 +2882,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 +2909,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 +2934,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 +2960,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 +3000,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 +3017,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 +3051,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 +3123,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 *