Doc: edit find plugin API docs

Edit for grammar and style. Remove \brief commands from
function descriptions.

Change-Id: I1f8c861f2f202f0af9056d639d6807b68ac517a2
Reviewed-by: Eike Ziller <eike.ziller@digia.com>

src/plugins/find/ifindfilter.cpp

@@ -35,15 +35,15 @@
 /*!
     \class Find::IFindFilter
     \brief The IFindFilter class is the base class for find implementations
-    that are invoked via the \gui{Edit -> Find/Replace -> Advanced Find}
+    that are invoked by selecting \gui Edit > \gui {Find/Replace} >
-    dialog.
+    \gui {Advanced Find}.
 
-    Implementations of this class add an additional "Scope" to the Advanced
+    Implementations of this class add an additional \gui Scope to the \gui {Advanced
-    Find dialog. That can be any search that requires the user to provide
+    Find} dialog. That can be any search that requires the user to provide
     a text based search term (potentially with find flags like
     searching case sensitively or using regular expressions). Existing
-    scopes are e.g. "All Projects" (i.e. search in all files in all projects)
+    scopes are \gui {All Projects} that searches from all files in all projects
-    and "Files on File System" where the user provides a directory and file
+    and \gui {Files on File System} where the user provides a directory and file
     patterns to search.
 
     To make your find scope available to the user, you need to implement this
@@ -57,8 +57,7 @@
     the details for this kind of search, only requiring you to provide an
     iterator over the file names of the files that should be searched.
 
-    If you want to implement a more specialized find filter, you'll need
+    If you want to implement a more specialized find filter, you need to:
-    to
     \list
         \li Start your search in a separate thread
         \li Make this known to the Core::ProgressManager, for a progress bar
@@ -75,7 +74,7 @@
 
     The common pattern is roughly this:
 
-    Implement the actual search within a QtConcurrent based method, i.e.
+    Implement the actual search within a QtConcurrent based method, that is
     a method that takes a \c{QFutureInterface<MySearchResult> &future}
     as the first parameter and the other information needed for the search
     as additional parameters. It should set useful progress information
@@ -101,25 +100,26 @@
 
 /*!
     \fn QString IFindFilter::id() const
-    \brief Unique string identifier for this find filter.
+    Returns the unique string identifier for this find filter.
 
     Usually should be something like "MyPlugin.MyFindFilter".
 */
 
 /*!
     \fn QString IFindFilter::displayName() const
-    \brief The name of the find filter/scope as presented to the user.
+    Returns the name of the find filter or scope as presented to the user.
 
-    This is the name that e.g. appears in the scope selection combo box.
+    This is the name that appears in the scope selection combo box, for example.
-    Always return a translatable string (i.e. use tr() for the return value).
+    Always return a translatable string (that is, use tr() for the return value).
 */
 
 /*!
     \fn bool IFindFilter::isEnabled() const
-    \brief Returns if the user should be able to select this find filter
+    Returns whether the user should be able to select this find filter
     at the moment.
 
-    This is used e.g. for the "Current Projects" scope - if the user hasn't
+    This is used for the \gui {Current Projects} scope, for example. If the user
+    has not
     opened a project, the scope is disabled.
 
     \sa changed()
@@ -127,8 +127,8 @@
 
 /*!
     \fn QKeySequence IFindFilter::defaultShortcut() const
-    \brief Returns the shortcut that can be used to open the advanced find
+    Returns the shortcut that can be used to open the advanced find
-    dialog with this filter/scope preselected.
+    dialog with this filter or scope preselected.
 
     Usually return an empty shortcut here, the user can still choose and
     assign a specific shortcut to this find scope via the preferences.
@@ -136,22 +136,22 @@
 
 /*!
     \fn bool IFindFilter::isReplaceSupported() const
-    \brief Returns if the find filter supports search and replace.
+    Returns whether the find filter supports search and replace.
 
-    The default value is false, override this method to return true, if
+    The default value is false, override this method to return \c true, if
     your find filter supports global search and replace.
 */
 
 /*!
     \fn void IFindFilter::findAll(const QString &txt, Find::FindFlags findFlags)
-    \brief This method is called when the user selected this find scope and
+    This method is called when the user selected this find scope and
     initiated a search.
 
     You should start a thread which actually performs the search for \a txt
     using the given \a findFlags
     (add it to Core::ProgressManager for a progress bar!) and presents the
     search results to the user (using the \gui{Search Results} output pane).
-    For more information see the descriptions of this class,
+    For more information, see the descriptions of this class,
     Core::ProgressManager, and Find::SearchResultWindow.
 
     \sa replaceAll()
@@ -161,7 +161,7 @@
 
 /*!
     \fn void IFindFilter::replaceAll(const QString &txt, Find::FindFlags findFlags)
-    \brief Override this method if you want to support search and replace.
+    Override this method if you want to support search and replace.
 
     This method is called when the user selected this find scope and
     initiated a search and replace.
@@ -181,33 +181,34 @@
 
 /*!
     \fn QWidget *IFindFilter::createConfigWidget()
-    \brief Return a widget that contains additional controls for options
+    Returns a widget that contains additional controls for options
     for this find filter.
 
-    The widget will be shown below the common options in the Advanced Find
+    The widget will be shown below the common options in the \gui {Advanced Find}
     dialog. It will be reparented and deleted by the find plugin.
 */
 
 /*!
     \fn void IFindFilter::writeSettings(QSettings *settings)
-    \brief Called at shutdown to write the state of the additional options
+    Called at shutdown to write the state of the additional options
     for this find filter to the \a settings.
 */
 
 /*!
     \fn void IFindFilter::readSettings(QSettings *settings)
-    \brief Called at startup to read the state of the additional options
+    Called at startup to read the state of the additional options
     for this find filter from the \a settings.
 */
 
 /*!
-    \fn void IFindFilter::changed()
+    \fn void IFindFilter::enabledChanged(bool enabled)
-    \brief Signals that the enabled state of this find filter has changed.
+
+    Signals that the enabled state of this find filter has changed.
 */
 
 /*!
     \fn Find::FindFlags BaseTextFind::supportedFindFlags() const
-    \brief Returns the find flags, like whole words or regular expressions,
+    Returns the find flags, like whole words or regular expressions,
     that this find filter supports.
 
     Depending on the returned value, the default find option widgets are

src/plugins/find/searchresultwindow.cpp

@@ -191,10 +191,10 @@ using namespace Find::Internal;
 
 /*!
     \enum Find::SearchResultWindow::SearchMode
-    Specifies if a search should show the replace UI or not.
+    This enum type specifies whether a search should show the replace UI or not:
 
     \value SearchOnly
-           The search doesn't support replace.
+           The search does not support replace.
     \value SearchAndReplace
            The search supports replace, so show the UI for it.
 */
@@ -211,14 +211,14 @@ using namespace Find::Internal;
 
 /*!
     \fn void SearchResult::activated(const Find::SearchResultItem &item)
-    \brief Sent if the user activated (e.g. double-clicked) a search result
+    Indicates that the user activated the search result \a item by
-    \a item.
+    double-clicking it, for example.
 */
 
 /*!
     \fn void SearchResult::replaceButtonClicked(const QString &replaceText, const QList<Find::SearchResultItem> &checkedItems, bool preserveCase)
-    \brief Sent when the user initiated a replace, e.g. by pressing the replace
+    Indicates that the user initiated a text replace by selecting
-    all button.
+    \gui {Replace All}, for example.
 
     The signal reports the text to use for replacement in \a replaceText,
     and the list of search result items that were selected by the user
@@ -243,14 +243,14 @@ using namespace Find::Internal;
     selecting an entry and performing a global replace.
 
     Whenever you start a search, call startNewSearch(SearchMode) to initialize
-    the search result window. The parameter determines if the GUI for
+    the \gui {Search Results} output pane. The parameter determines if the GUI for
     replacing should be shown.
     The method returns a SearchResult object that is your
     hook into the signals from user interaction for this search.
     When you produce search results, call addResults or addResult to add them
-    to the search result window.
+    to the \gui {Search Results} output pane.
-    After the search has finished call finishSearch to inform the search
+    After the search has finished call finishSearch to inform the
-    result window about it.
+    \gui {Search Results} output pane about it.
 
     You will get activated signals via your SearchResult instance when
     the user selects a search result item, and, if you started the search
@@ -317,7 +317,7 @@ SearchResultWindow::~SearchResultWindow()
 }
 
 /*!
-    \brief Returns the single shared instance of the Search Results window.
+    Returns the single shared instance of the \gui {Search Results} output pane.
 */
 SearchResultWindow *SearchResultWindow::instance()
 {
@@ -350,12 +350,12 @@ QList<QWidget*> SearchResultWindow::toolBarWidgets() const
 }
 
 /*!
-    \brief Tells the search results window to start a new search.
+    Tells the \gui {Search Results} output pane to start a new search.
 
-    The \a label should be a string that shortly describes the type of
+    The \a label should be a string that shortly describes the type of the
-    search, i.e. search filter and possibly a most relevant search option, followed by a colon ':'.
+    search, that is, the search filter and possibly the most relevant search
-    E.g. \code{Project 'myproject':}
+     option, followed by a colon ':'. For example: \c {Project 'myproject':}
-    The \a searchTerm will be shown behind the colon.
+    The \a searchTerm is shown after the colon.
     The \a toolTip should elaborate on the search parameters, like file patterns that are searched and
     find flags.
     If \a cfgGroup is not empty, it will be used for storing the "do not ask again"
@@ -365,7 +365,8 @@ QList<QWidget*> SearchResultWindow::toolBarWidgets() const
     with the results of this search.
     The search result window owns the returned SearchResult
     and might delete it any time, even while the search is running
-    (e.g. when the user clears the search result pane, or if the user opens so many other searches
+    (for example, when the user clears the \gui {Search Results} pane, or when
+    the user opens so many other searches
     that this search falls out of the history).
 
 */
@@ -408,7 +409,7 @@ SearchResult *SearchResultWindow::startNewSearch(const QString &label,
 }
 
 /*!
-    \brief Clears the current contents in the search result window.
+    Clears the current contents of the \gui {Search Results} output pane.
 */
 void SearchResultWindow::clearContents()
 {
@@ -600,7 +601,7 @@ SearchResult::SearchResult(SearchResultWidget *widget)
 }
 
 /*!
-    \brief Attach some random \a data to this search, that you can use later.
+    Attaches some random \a data to this search, that you can use later.
 
     \sa userData()
 */
@@ -610,7 +611,8 @@ void SearchResult::setUserData(const QVariant &data)
 }
 
 /*!
-    \brief Return the data that was attached to this search by calling setUserData().
+    Returns the data that was attached to this search by calling
+    setUserData().
 
     \sa setUserData()
 */
@@ -620,7 +622,7 @@ QVariant SearchResult::userData() const
 }
 
 /*!
-    \brief Returns the text that should replace the text in search results.
+    Returns the text that should replace the text in search results.
 */
 QString SearchResult::textToReplace() const
 {
@@ -638,13 +640,14 @@ void SearchResult::setSearchAgainSupported(bool supported)
 }
 
 /*!
-    \brief Adds a single result line to the search results.
+    Adds a single result line to the \gui {Search Results} output pane.
 
-    The \a fileName, \a lineNumber and \a rowText are shown in the result line.
+    \a fileName, \a lineNumber, and \a lineText are shown on the result line.
     \a searchTermStart and \a searchTermLength specify the region that
-    should be visually marked (string position and length in \a rowText).
+    should be visually marked (string position and length in \a lineText).
     You can attach arbitrary \a userData to the search result, which can
-    be used e.g. when reacting to the signals of the SearchResult for your search.
+    be used, for example, when reacting to the signals of the search results
+    for your search.
 
     \sa addResults()
 */
@@ -657,8 +660,7 @@ void SearchResult::addResult(const QString &fileName, int lineNumber, const QStr
 }
 
 /*!
-    \brief Adds all of the given search result \a items to the search
+    Adds the search result \a items to the \gui {Search Results} output pane.
-    results window.
 
     \sa addResult()
 */
@@ -669,7 +671,7 @@ void SearchResult::addResults(const QList<SearchResultItem> &items, AddMode mode
 }
 
 /*!
-    \brief Notifies the search result window that the current search
+    Notifies the \gui {Search Results} output pane that the current search
     has finished, and the UI should reflect that.
 */
 void SearchResult::finishSearch(bool canceled)
@@ -678,7 +680,7 @@ void SearchResult::finishSearch(bool canceled)
 }
 
 /*!
-    \brief Sets the value in the UI element that allows the user to type
+    Sets the value in the UI element that allows the user to type
     the text that should replace text in search results to \a textToReplace.
 */
 void SearchResult::setTextToReplace(const QString &textToReplace)
@@ -687,7 +689,7 @@ void SearchResult::setTextToReplace(const QString &textToReplace)
 }
 
 /*!
- * \brief Removes all search results.
+ * Removes all search results.
  */
 void SearchResult::restart()
 {
@@ -700,7 +702,7 @@ void SearchResult::setSearchAgainEnabled(bool enabled)
 }
 
 /*!
- * \brief Pops up the search result panel with this search.
+ * Opens the \gui {Search Results} output pane with this search.
  */
 void SearchResult::popup()
 {