GNOME.org
 

[gtksourceview/wip/regex-search: 3/10] Adapt the documentation for the new search API

commit eecd7d712b69de9e57a97fc284a63fb66895328f
Author: Sébastien Wilmet <swilmet gnome org>
Date:   Wed Jul 31 13:22:21 2013 +0200

    Adapt the documentation for the new search API

 docs/reference/gtksourceview-3.0-sections.txt |   58 ++++++++++++++++++++
 docs/reference/gtksourceview-docs.xml         |    2 +
 gtksourceview/gtksourcebuffer.c               |   41 --------------
 gtksourceview/gtksourcesearchcontext.c        |   72 ++++++++++++++++++++++++-
 gtksourceview/gtksourcesearchsettings.c       |   11 ++++
 gtksourceview/gtksourceutils.c                |   10 ++--
 6 files changed, 147 insertions(+), 47 deletions(-)
---
diff --git a/docs/reference/gtksourceview-3.0-sections.txt b/docs/reference/gtksourceview-3.0-sections.txt
index 33f62aa..f7a9f97 100644
--- a/docs/reference/gtksourceview-3.0-sections.txt
+++ b/docs/reference/gtksourceview-3.0-sections.txt
@@ -470,6 +470,64 @@ GtkSourcePrintCompositorClass
 </SECTION>
 
 <SECTION>
+<FILE>searchcontext</FILE>
+<TITLE>GtkSourceSearchContext</TITLE>
+GtkSourceSearchContext
+gtk_source_search_context_new
+gtk_source_search_context_get_buffer
+gtk_source_search_context_get_settings
+gtk_source_search_context_set_settings
+gtk_source_search_context_get_occurrences_count
+gtk_source_search_context_get_occurrence_position
+gtk_source_search_context_forward
+gtk_source_search_context_forward_async
+gtk_source_search_context_forward_finish
+gtk_source_search_context_backward
+gtk_source_search_context_backward_async
+gtk_source_search_context_backward_finish
+gtk_source_search_context_replace
+gtk_source_search_context_replace_all
+gtk_source_search_context_get_regex_error
+<SUBSECTION Standard>
+GTK_SOURCE_IS_SEARCH_CONTEXT
+GTK_SOURCE_IS_SEARCH_CONTEXT_CLASS
+GTK_SOURCE_SEARCH_CONTEXT
+GTK_SOURCE_SEARCH_CONTEXT_CLASS
+GTK_SOURCE_SEARCH_CONTEXT_GET_CLASS
+GTK_SOURCE_TYPE_SEARCH_CONTEXT
+GtkSourceSearchContextClass
+GtkSourceSearchContextPrivate
+gtk_source_search_context_get_type
+</SECTION>
+
+<SECTION>
+<FILE>searchsettings</FILE>
+<TITLE>GtkSourceSearchSettings</TITLE>
+GtkSourceSearchSettings
+gtk_source_search_settings_new
+gtk_source_search_settings_get_search_text
+gtk_source_search_settings_set_search_text
+gtk_source_search_settings_get_case_sensitive
+gtk_source_search_settings_set_case_sensitive
+gtk_source_search_settings_get_at_word_boundaries
+gtk_source_search_settings_set_at_word_boundaries
+gtk_source_search_settings_get_wrap_around
+gtk_source_search_settings_set_wrap_around
+gtk_source_search_settings_get_regex_enabled
+gtk_source_search_settings_set_regex_enabled
+<SUBSECTION Standard>
+GTK_SOURCE_IS_SEARCH_SETTINGS
+GTK_SOURCE_IS_SEARCH_SETTINGS_CLASS
+GTK_SOURCE_SEARCH_SETTINGS
+GTK_SOURCE_SEARCH_SETTINGS_CLASS
+GTK_SOURCE_SEARCH_SETTINGS_GET_CLASS
+GTK_SOURCE_TYPE_SEARCH_SETTINGS
+GtkSourceSearchSettingsClass
+GtkSourceSearchSettingsPrivate
+gtk_source_search_settings_get_type
+</SECTION>
+
+<SECTION>
 <FILE>style</FILE>
 <TITLE>GtkSourceStyle</TITLE>
 GtkSourceStyle
diff --git a/docs/reference/gtksourceview-docs.xml b/docs/reference/gtksourceview-docs.xml
index 90fee63..a21631e 100644
--- a/docs/reference/gtksourceview-docs.xml
+++ b/docs/reference/gtksourceview-docs.xml
@@ -33,6 +33,8 @@
     <xi:include href="xml/mark.xml"/>
     <xi:include href="xml/markattributes.xml"/>
     <xi:include href="xml/printcompositor.xml"/>    
+    <xi:include href="xml/searchcontext.xml"/>
+    <xi:include href="xml/searchsettings.xml"/>
     <xi:include href="xml/style.xml"/>
     <xi:include href="xml/stylescheme.xml"/>
     <xi:include href="xml/styleschememanager.xml"/>
diff --git a/gtksourceview/gtksourcebuffer.c b/gtksourceview/gtksourcebuffer.c
index e6cd89e..6998473 100644
--- a/gtksourceview/gtksourcebuffer.c
+++ b/gtksourceview/gtksourcebuffer.c
@@ -86,47 +86,6 @@
  *     and gtk_text_buffer_set_modified().
  *   </para>
  * </refsect2>
- * <refsect2>
- *   <title>Search and Replace</title>
- *   <warning>
- *     <para>
- *       The search and replace API is unstable and will most probably
- *       change in the near future.
- *     </para>
- *   </warning>
- *   <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,
- *     #GtkSourceBuffer:search-wrap-around and
- *     #GtkSourceBuffer:regex-search.
- *   </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>
- *   <para>
- *     In the GtkSourceView source code, there is an example of how to use the
- *     search and replace API: see the tests/test-search.c file. It is a mini
- *     application for the search and replace, with a basic user interface.
- *   </para>
- * </refsect2>
  */
 
 /*
diff --git a/gtksourceview/gtksourcesearchcontext.c b/gtksourceview/gtksourcesearchcontext.c
index 8e05cbf..64e29cd 100644
--- a/gtksourceview/gtksourcesearchcontext.c
+++ b/gtksourceview/gtksourcesearchcontext.c
@@ -30,6 +30,38 @@
 
 #include <string.h>
 
+/**
+ * SECTION:searchcontext
+ * @Short_description: The context of a search
+ * @Title: GtkSourceSearchContext
+ * @See_also: #GtkSourceBuffer, #GtkSourceSearchSettings
+ *
+ * A #GtkSourceSearchContext is used for the search and replace in a
+ * #GtkSourceBuffer. The search settings are represented by a
+ * #GtkSourceSearchSettings object, that can be shared between several
+ * #GtkSourceSearchContext<!-- -->s. A buffer can contain several search
+ * contexts at the same time, but at most one search context per buffer can
+ * highlight its search occurrences.
+ *
+ * The total number of search occurrences can be retrieved with
+ * gtk_source_search_context_get_occurrences_count(). To know the position of a
+ * certain match, use gtk_source_search_context_get_occurrence_position().
+ *
+ * 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.
+ *
+ * To search forward, use gtk_source_search_context_forward() or
+ * gtk_source_search_context_forward_async() for the asynchronous version.
+ * The backward search is done similarly. To replace a search match, or all
+ * matches, use gtk_source_search_context_replace() and
+ * gtk_source_search_context_replace_all().
+ *
+ * In the GtkSourceView source code, there is an example of how to use the
+ * search and replace API: see the tests/test-search.c file. It is a mini
+ * application for the search and replace, with a basic user interface.
+ */
+
 /* Implementation overview:
  *
  * When the state of the search changes (the text to search or the options), we
@@ -2705,6 +2737,19 @@ gtk_source_search_context_init (GtkSourceSearchContext *search)
        search->priv = gtk_source_search_context_get_instance_private (search);
 }
 
+/**
+ * gtk_source_search_context_new:
+ * @buffer: a #GtkSourceBuffer.
+ * @settings: (allow-none): a #GtkSourceSearchSettings, or %NULL.
+ *
+ * Creates a new search context, associated with @buffer, and customized with
+ * @settings. If @settings is %NULL, a new #GtkSourceSearchSettings object will
+ * be created, that you can retrieve with
+ * gtk_source_search_context_get_settings().
+ *
+ * Returns: a new search context.
+ * Since: 3.10
+ */
 GtkSourceSearchContext *
 gtk_source_search_context_new (GtkSourceBuffer         *buffer,
                               GtkSourceSearchSettings *settings)
@@ -2718,6 +2763,13 @@ gtk_source_search_context_new (GtkSourceBuffer         *buffer,
                             NULL);
 }
 
+/**
+ * gtk_source_search_context_get_buffer:
+ * @search: a #GtkSourceSearchContext.
+ *
+ * Returns: (transfer none): the associated buffer.
+ * Since: 3.10
+ */
 GtkSourceBuffer *
 gtk_source_search_context_get_buffer (GtkSourceSearchContext *search)
 {
@@ -2726,6 +2778,13 @@ gtk_source_search_context_get_buffer (GtkSourceSearchContext *search)
        return GTK_SOURCE_BUFFER (search->priv->buffer);
 }
 
+/**
+ * gtk_source_search_context_get_settings:
+ * @search: a #GtkSourceSearchContext.
+ *
+ * Returns: (transfer none): the search settings.
+ * Since: 3.10
+ */
 GtkSourceSearchSettings *
 gtk_source_search_context_get_settings (GtkSourceSearchContext *search)
 {
@@ -2734,6 +2793,17 @@ gtk_source_search_context_get_settings (GtkSourceSearchContext *search)
        return get_settings (search);
 }
 
+/**
+ * gtk_source_search_context_set_settings:
+ * @search: a #GtkSourceSearchContext.
+ * @settings: the new #GtkSourceSearchSettings.
+ *
+ * Associate a #GtkSourceSearchSettings with the search context.
+ *
+ * The search context holds a reference to @settings.
+ *
+ * Since: 3.10
+ */
 void
 gtk_source_search_context_set_settings (GtkSourceSearchContext  *search,
                                        GtkSourceSearchSettings *settings)
@@ -2770,7 +2840,7 @@ gtk_source_search_context_set_settings (GtkSourceSearchContext  *search,
  * @search: a #GtkSourceSearchContext.
  *
  * Regular expression patterns must follow certain rules. If
- * #GtkSourceSearchContext:search-text breaks a rule, the error can be retrieved
+ * #GtkSourceSearchSettings:search-text breaks a rule, the error can be retrieved
  * with this function. The error domain is #G_REGEX_ERROR.
  *
  * Free the return value with g_error_free().
diff --git a/gtksourceview/gtksourcesearchsettings.c b/gtksourceview/gtksourcesearchsettings.c
index 9a66a90..e3556bd 100644
--- a/gtksourceview/gtksourcesearchsettings.c
+++ b/gtksourceview/gtksourcesearchsettings.c
@@ -22,6 +22,17 @@
 #include "gtksourcesearchsettings.h"
 #include "gtksourceview-i18n.h"
 
+/**
+ * SECTION:searchsettings
+ * @Short_description: The settings of a search
+ * @Title: GtkSourceSearchSettings
+ * @See_also: #GtkSourceSearchContext
+ *
+ * A #GtkSourceSearchSettings object represents the settings of a search. The
+ * search settings can be associated with one or several
+ * #GtkSourceSearchContext<!-- -->s.
+ */
+
 enum
 {
        PROP_0,
diff --git a/gtksourceview/gtksourceutils.c b/gtksourceview/gtksourceutils.c
index 4023ef3..9778196 100644
--- a/gtksourceview/gtksourceutils.c
+++ b/gtksourceview/gtksourceutils.c
@@ -35,9 +35,9 @@
  * gtk_source_utils_unescape_search_text:
  * @text: the text to unescape.
  *
- * Use this function before gtk_source_buffer_set_search_text(), to unescape
- * certain sequences of characters: \n, \r, \t and \\. The purpose is to easily
- * write those characters in a search entry.
+ * Use this function before gtk_source_search_settings_set_search_text(), to
+ * unescape certain sequences of characters: \n, \r, \t and \\. The purpose is
+ * to easily write those characters in a search entry.
  *
  * See also: gtk_source_utils_escape_search_text().
  *
@@ -124,8 +124,8 @@ gtk_source_utils_unescape_search_text (const gchar *text)
  * gtk_source_utils_escape_search_text:
  * @text: the text to escape.
  *
- * Use this function after gtk_source_buffer_get_search_text(), to escape
- * certain characters: \n, \r, \t and \.
+ * Use this function after gtk_source_search_settings_get_search_text(), to
+ * escape certain characters: \n, \r, \t and \.
  *
  * See also: gtk_source_utils_unescape_search_text().
  *
[Date Prev][Date Next]   [Thread Prev][Thread Next]   [Thread Index] [Date Index] [Author Index]