[devhelp] Update some comments related to search

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

commit 443bca87551162912d0c6d51a1c3219e6e5d2719
Author: Sébastien Wilmet <swilmet gnome org>
Date:   Mon Jan 22 13:27:19 2018 +0100

    Update some comments related to search

 src/dh-search-context.c |   22 +++++-----------------
 src/dh-sidebar.c        |    6 +-----
 2 files changed, 6 insertions(+), 22 deletions(-)
---
diff --git a/src/dh-search-context.c b/src/dh-search-context.c
index a8b31bb..8212434 100644
--- a/src/dh-search-context.c
+++ b/src/dh-search-context.c
@@ -430,31 +430,19 @@ _dh_search_context_match_link (DhSearchContext *search,
         g_return_val_if_fail (link_name != NULL, FALSE);
 
         /* Why isn't there only one GPatternSpec (or two variants:
-         * prefix/nonprefix) for all the keywords? For example searching
+         * prefix/anywhere) for all the keywords? For example searching
          * "dh_link_ book" (two keywords) would create the GPatternSpec
          * "dh_link_*book*". Although the implementation would be simpler, doing
-         * so would be a regression in functionality, because with one
-         * GPatternSpec for each keyword, the keywords don't necessarily need to
-         * be in the same order as in the DhLink name. With "dh_link_*book*", it
-         * forces "book" to be after "dh_link_". And anyway if the user wants to
-         * enforce the appearance order of the keywords, she can use the '*'
-         * glob in the search string.
-         *
-         * A good example is the search string "gtk window application", it
-         * matches both gtk_window_get_application() and GtkApplicationWindow
-         * (among other symbols).
-         *
-         * To enforce the appearance order of the keywords, the '*' glob can be
-         * used: "gtk*window*application" will match
-         * gtk_window_get_application(), but not GtkApplicationWindow.
+         * so would be a regression in functionality. It is explained in details
+         * in the user documentation of the Devhelp app.
          */
 
         /* Why matching by prefix only for the first keyword and not the others?
          * For several reasons:
          * - When prefix=TRUE, if data->pattern_spec_prefix was used for all
          *   keywords, it would be impossible to match the DhLink name (except
-         *   if all the keywords are equal, but it doesn't make sense to do such
-         *   a search).
+         *   if all the keywords are equal for example, but it doesn't make
+         *   sense to do such a search).
          * - At least with the GTK+/GNOME APIs, normally all the symbols start
          *   with the namespace of the library. So when we search symbols, if we
          *   know in which library the symbol(s) is located, we can type the
diff --git a/src/dh-sidebar.c b/src/dh-sidebar.c
index 19ceae8..e939c1b 100644
--- a/src/dh-sidebar.c
+++ b/src/dh-sidebar.c
@@ -136,11 +136,7 @@ search_idle_cb (gpointer user_data)
         book_link = dh_book_tree_get_selected_book (priv->book_tree);
         book_id = book_link != NULL ? dh_link_get_book_id (book_link) : NULL;
 
-        /* Disconnect the model during the filter, for:
-         * 1. Better performances.
-         * 2. Clearing the selection.
-         * 3. Because it's required by dh_keyword_model_filter().
-         */
+        /* Disconnect the model, see the doc of dh_keyword_model_filter(). */
         gtk_tree_view_set_model (priv->hitlist_view, NULL);
 
         exact_link = dh_keyword_model_filter (priv->hitlist_model,