Doc: Fix QDoc warnings in Find classes

- Document BaseTextFind and FindSupport
- Mark undocumented classes and namespaces \internal
- Add and fix docs for IFindFilter, SearchResult, and
  SearchResultWindow

Fixes: QTCREATORBUG-23600
Change-Id: Ic9445f7f15562f114f4cbd9fe16988d7249d48db
Reviewed-by: Eike Ziller <eike.ziller@qt.io>

doc/qtcreatordev/src/common-extension-tasks.qdoc

@@ -86,13 +86,13 @@
         \row
             \li Add a find filter to the \uicontrol Find dialog.
             \li Implement any kind of search term based search.
-            \li \l{Find::IFindFilter}, \l{Core::SearchResultWindow}
+            \li \l{Core::IFindFilter}, \l{Core::SearchResultWindow}
 
         \row
             \li Add support for the find tool bar to a widget.
             \li The widget that has focus is asked whether it supports text
                 search. You can add support for widgets under your control.
-            \li \l{Core::IFindSupport}, \l{Find::BaseTextFind}
+            \li \l{Core::IFindSupport}, \l{Core::BaseTextFind}
 
         \omit
         \row
@@ -111,8 +111,7 @@
             \li For a text typed in by the user you provide a list of things to
                 show in the popup. When the user selects an entry you are
                 requested to do whatever you want.
-            \li \l{Core::ILocatorFilter}, \l{Core::LocatorFilterEntry},
+            \li \l{Core::ILocatorFilter}, \l{Core::BaseFileFilter}
-                \l{Locator::BaseFileFilter}
 
         \row
             \li Show a progress indicator for a concurrently running task.

src/plugins/coreplugin/find/basetextfind.cpp

@@ -81,17 +81,54 @@ BaseTextFindPrivate::BaseTextFindPrivate(QPlainTextEdit *editor)
 {
 }
 
+/*!
+    \class Core::BaseTextFind
+    \inmodule QtCreator
+
+    \brief The BaseTextFind class implements a find filter for QPlainTextEdit
+    and QTextEdit based widgets.
+
+    \sa Core::IFindFilter
+*/
+
+/*!
+    \fn void BaseTextFind::findScopeChanged(const QTextCursor &start,
+                           const QTextCursor &end,
+                           int verticalBlockSelectionFirstColumn,
+                           int verticalBlockSelectionLastColumn)
+
+    This signal is emitted when the search
+    scope changes to \a start, \a end,
+    \a verticalBlockSelectionFirstColumn, and
+    \a verticalBlockSelectionLastColumn.
+*/
+
+/*!
+    \fn void BaseTextFind::highlightAllRequested(const QString &txt, Core::FindFlags findFlags)
+
+    This signal is emitted when the search results for \a txt using the given
+    \a findFlags should be highlighted in the editor widget.
+*/
+
+/*!
+    \internal
+*/
 BaseTextFind::BaseTextFind(QTextEdit *editor)
     : d(new BaseTextFindPrivate(editor))
 {
 }
 
-
+/*!
+    \internal
+*/
 BaseTextFind::BaseTextFind(QPlainTextEdit *editor)
     : d(new BaseTextFindPrivate(editor))
 {
 }
 
+/*!
+    \internal
+*/
 BaseTextFind::~BaseTextFind()
 {
     delete d;
@@ -121,28 +158,43 @@ bool BaseTextFind::isReadOnly() const
     return d->m_editor ? d->m_editor->isReadOnly() : d->m_plaineditor->isReadOnly();
 }
 
+/*!
+    \reimp
+*/
 bool BaseTextFind::supportsReplace() const
 {
     return !isReadOnly();
 }
 
+/*!
+    \reimp
+*/
 FindFlags BaseTextFind::supportedFindFlags() const
 {
     return FindBackward | FindCaseSensitively | FindRegularExpression
             | FindWholeWords | FindPreserveCase;
 }
 
+/*!
+    \reimp
+*/
 void BaseTextFind::resetIncrementalSearch()
 {
     d->m_incrementalStartPos = -1;
     d->m_incrementalWrappedState = false;
 }
 
+/*!
+    \reimp
+*/
 void BaseTextFind::clearHighlights()
 {
     highlightAll(QString(), {});
 }
 
+/*!
+    \reimp
+*/
 QString BaseTextFind::currentFindString() const
 {
     QTextCursor cursor = textCursor();
@@ -168,6 +220,9 @@ QString BaseTextFind::currentFindString() const
     return QString();
 }
 
+/*!
+    \reimp
+*/
 QString BaseTextFind::completedFindString() const
 {
     QTextCursor cursor = textCursor();
@@ -176,6 +231,9 @@ QString BaseTextFind::completedFindString() const
     return cursor.selectedText();
 }
 
+/*!
+    \reimp
+*/
 IFindSupport::Result BaseTextFind::findIncremental(const QString &txt, FindFlags findFlags)
 {
     QTextCursor cursor = textCursor();
@@ -195,6 +253,9 @@ IFindSupport::Result BaseTextFind::findIncremental(const QString &txt, FindFlags
     return found ? Found : NotFound;
 }
 
+/*!
+    \reimp
+*/
 IFindSupport::Result BaseTextFind::findStep(const QString &txt, FindFlags findFlags)
 {
     bool wrapped = false;
@@ -208,6 +269,9 @@ IFindSupport::Result BaseTextFind::findStep(const QString &txt, FindFlags findFl
     return found ? Found : NotFound;
 }
 
+/*!
+    \reimp
+*/
 void BaseTextFind::replace(const QString &before, const QString &after, FindFlags findFlags)
 {
     QTextCursor cursor = replaceInternal(before, after, findFlags);
@@ -259,6 +323,9 @@ QTextCursor BaseTextFind::replaceInternal(const QString &before, const QString &
     return cursor;
 }
 
+/*!
+    \reimp
+*/
 bool BaseTextFind::replaceStep(const QString &before, const QString &after, FindFlags findFlags)
 {
     QTextCursor cursor = replaceInternal(before, after, findFlags);
@@ -269,6 +336,10 @@ bool BaseTextFind::replaceStep(const QString &before, const QString &after, Find
     return found;
 }
 
+/*!
+    \reimp
+    Returns the number of search hits replaced.
+*/
 int BaseTextFind::replaceAll(const QString &before, const QString &after, FindFlags findFlags)
 {
     QTextCursor editCursor = textCursor();
@@ -408,6 +479,9 @@ bool BaseTextFind::inScope(int startPosition, int endPosition) const
             && d->m_findScopeEnd.position() >= endPosition);
 }
 
+/*!
+    \reimp
+*/
 void BaseTextFind::defineFindScope()
 {
     QTextCursor cursor = textCursor();
@@ -436,6 +510,9 @@ void BaseTextFind::defineFindScope()
     }
 }
 
+/*!
+    \reimp
+*/
 void BaseTextFind::clearFindScope()
 {
     d->m_findScopeStart = QTextCursor();
@@ -447,6 +524,10 @@ void BaseTextFind::clearFindScope()
                           d->m_findScopeVerticalBlockSelectionLastColumn);
 }
 
+/*!
+    \reimp
+    Emits highlightAllRequested().
+*/
 void BaseTextFind::highlightAll(const QString &txt, FindFlags findFlags)
 {
     emit highlightAllRequested(txt, findFlags);

src/plugins/coreplugin/find/findplugin.cpp

@@ -53,11 +53,13 @@
 #include <QSettings>
 
 /*!
-    \namespace Core::Internal
+    \namespace Core::Internal::ItemDataRoles
     \internal
 */
+
 /*!
-    \namespace Core::Internal::ItemDataRoles
+    \class Core::Find
+    \inmodule QtCreator
     \internal
 */
 

src/plugins/coreplugin/find/highlightscrollbarcontroller.cpp

@@ -36,6 +36,18 @@
 using namespace Utils;
 namespace Core {
 
+/*!
+    \class Core::Highlight
+    \inmodule QtCreator
+    \internal
+*/
+
+/*!
+    \class Core::HighlightScrollBarController
+    \inmodule QtCreator
+    \internal
+*/
+
 class HighlightScrollBarOverlay : public QWidget
 {
 public:

src/plugins/coreplugin/find/ifindfilter.cpp

@@ -33,27 +33,32 @@
 #include <QPixmap>
 
 /*!
-    \class Find::IFindFilter
+    \class Core::IFindFilter
+    \inmodule QtCreator
     \brief The IFindFilter class is the base class for find implementations
-    that are invoked by selecting \gui Edit > \gui {Find/Replace} >
+    that are invoked by selecting \uicontrol Edit > \uicontrol {Find/Replace} >
-    \gui {Advanced Find}.
+    \uicontrol {Advanced Find}.
 
-    Implementations of this class add an additional \gui Scope to the \gui {Advanced
+    Implementations of this class add an additional \uicontrol Scope to the \uicontrol {Advanced
     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 \gui {All Projects} that searches from all files in all projects
+    scopes are \uicontrol {All Projects} that searches from all files in all projects
-    and \gui {Files in File System} where the user provides a directory and file
+    and \uicontrol {Files in File System} where the user provides a directory and file
     patterns to search.
 
+    \image qtcreator-search-filesystem.png
+
     To make your find scope available to the user, you need to implement this
     class, and register an instance of your subclass in the plugin manager.
 
     A common way to present the search results to the user, is to use the
-    shared \gui{Search Results} panel.
+    shared \uicontrol{Search Results} pane.
+
+    \image qtcreator-searchresults.png
 
     If you want to implement a find filter that is doing a file based text
-    search, you should use Find::BaseFileFind, which already implements all
+    search, you should use \l Core::BaseTextFind, which already implements all
     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.
 
@@ -62,19 +67,18 @@
         \li Start your search in a separate thread
         \li Make this known to the Core::ProgressManager, for a progress bar
            and the ability to cancel the search
-        \li Interface with the shared \gui{Search Results} panel, to show
+        \li Interface with the shared \uicontrol{Search Results} pane, to show
            the search results, handle the event that the user click on one
            of the search result items, and possible handle a global replace
            of all or some of the search result items.
     \endlist
 
-    Luckily QtConcurrent and the search result panel provide the frameworks
+    Luckily QtConcurrent and the search results pane provide the frameworks
     that make it relatively easy to implement,
     while ensuring a common way for the user.
 
-    The common pattern is roughly this:
+    The common pattern is roughly to first implement the actual search
-
+    within a QtConcurrent based function. That is
-    Implement the actual search within a QtConcurrent based function, that is
     a function 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
@@ -82,21 +86,17 @@
     and \c{future.isCanceled()}, and report the search results
     (possibly in chunks) via \c{future.reportResult}.
 
-    In the find filter's find/replaceAll function, get the shared
+    In the find filter's \c find() or \c replaceAll() function, get the shared
-    \gui{Search Results} window, initiate a new search and connect the
+    \uicontrol{Search Results} window, initiate a new search and connect the
     signals for handling selection of results and the replace action
     (see the Core::SearchResultWindow class for details).
     Start your search implementation via the corresponding QtConcurrent
     functions. Add the returned QFuture object to the Core::ProgressManager.
     Use a QFutureWatcher on the returned QFuture object to receive a signal
     when your search implementation reports search results, and add these
-    to the shared \gui{Search Results} window.
+    to the shared \uicontrol{Search Results} window.
 */
 
-/*!
-    \fn IFindFilter::~IFindFilter()
-    \internal
-*/
 
 /*!
     \fn QString IFindFilter::id() const
@@ -110,7 +110,8 @@
     Returns the name of the find filter or scope as presented to the user.
 
     This is the name that appears in the scope selection combo box, for example.
-    Always return a translatable string (that is, use tr() for the return value).
+    Always return a translatable string. That is, use \c tr() for the return
+    value.
 */
 
 /*!
@@ -118,20 +119,18 @@
     Returns whether the user should be able to select this find filter
     at the moment.
 
-    This is used for the \gui {Current Projects} scope, for example. If the user
+    This is used for the \uicontrol {Current Projects} scope, for example. If the user
     has not
     opened a project, the scope is disabled.
 
-    \sa changed()
+    \sa enabledChanged()
 */
 
 /*!
-    \fn QKeySequence IFindFilter::defaultShortcut() const
+    \fn bool IFindFilter::isValid() const
-    Returns the shortcut that can be used to open the advanced find
+    Returns whether the find filter is valid.
-    dialog with this filter or scope preselected.
 
-    Usually return an empty shortcut here, the user can still choose and
+    \sa validChanged()
-    assign a specific shortcut to this find scope via the preferences.
 */
 
 /*!
@@ -143,7 +142,7 @@
 */
 
 /*!
-    \fn bool showSearchTermInput() const
+    \fn bool IFindFilter::showSearchTermInput() const
     Returns whether the find filter wants to show the search term line edit.
 
     The default value is \c true, override this function to return \c false, if
@@ -151,14 +150,14 @@
 */
 
 /*!
-    \fn void IFindFilter::findAll(const QString &txt, Core::FindFlags findFlags)
+    \fn void IFindFilter::findAll(const QString &txt, FindFlags findFlags)
     This function 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
+    (add it to Core::ProgressManager for a progress bar) and presents the
-    search results to the user (using the \gui{Search Results} output pane).
+    search results to the user (using the \uicontrol{Search Results} output pane).
     For more information, see the descriptions of this class,
     Core::ProgressManager, and Core::SearchResultWindow.
 
@@ -168,7 +167,7 @@
 */
 
 /*!
-    \fn void IFindFilter::replaceAll(const QString &txt, Core::FindFlags findFlags)
+    \fn void IFindFilter::replaceAll(const QString &txt, FindFlags findFlags)
     Override this function if you want to support search and replace.
 
     This function is called when the user selected this find scope and
@@ -177,8 +176,8 @@
 
     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
+    (add it to Core::ProgressManager for a progress bar) and presents the
-    search results to the user (using the \gui{Search Results} output pane).
+    search results to the user (using the \uicontrol{Search Results} output pane).
     For more information see the descriptions of this class,
     Core::ProgressManager, and Core::SearchResultWindow.
 
@@ -192,7 +191,7 @@
     Returns a widget that contains additional controls for options
     for this find filter.
 
-    The widget will be shown below the common options in the \gui {Advanced Find}
+    The widget will be shown below the common options in the \uicontrol {Advanced Find}
     dialog. It will be reparented and deleted by the find plugin.
 */
 
@@ -211,44 +210,71 @@
 /*!
     \fn void IFindFilter::enabledChanged(bool enabled)
 
-    Signals that the enabled state of this find filter has changed.
+    This signal is emitted when the \a enabled state of this find filter
+    changes.
 */
 
 /*!
-    \fn Core::FindFlags BaseTextFind::supportedFindFlags() const
+    \fn void IFindFilter::validChanged(bool valid)
-    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
+    This signal is emitted when the \a valid state of this find filter changes.
-    enabled or disabled.
+*/
-    The default is Find::FindCaseSensitively, Find::FindRegularExpression
+
-    and Find::FindWholeWords
+/*!
+    \fn void IFindFilter::displayNameChanged()
+
+    This signal is emitted when the display name of this find filter changes.
 */
 
 namespace Core {
 
 static QList<IFindFilter *> g_findFilters;
 
+/*!
+    \internal
+*/
 IFindFilter::IFindFilter()
 {
     g_findFilters.append(this);
 }
 
+/*!
+    \internal
+*/
 IFindFilter::~IFindFilter()
 {
     g_findFilters.removeOne(this);
 }
 
+/*!
+    Returns a list of find filters.
+*/
 const QList<IFindFilter *> IFindFilter::allFindFilters()
 {
     return g_findFilters;
 }
 
+/*!
+    Returns the shortcut that can be used to open the advanced find
+    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.
+*/
 QKeySequence IFindFilter::defaultShortcut() const
 {
     return QKeySequence();
 }
 
+/*!
+    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
+    enabled or disabled.
+    The default is Core::FindCaseSensitively, Core::FindRegularExpression
+    and Core::FindWholeWords.
+*/
 FindFlags IFindFilter::supportedFindFlags() const
 {
     return FindCaseSensitively
@@ -256,6 +282,9 @@ FindFlags IFindFilter::supportedFindFlags() const
          | FindWholeWords;
 }
 
+/*!
+    Returns icons for the find flags \a flags.
+*/
 QPixmap IFindFilter::pixmapForFindFlags(FindFlags flags)
 {
     static const QPixmap casesensitiveIcon = Icons::FIND_CASE_INSENSITIVELY.pixmap();
@@ -300,6 +329,9 @@ QPixmap IFindFilter::pixmapForFindFlags(FindFlags flags)
     return pixmap;
 }
 
+/*!
+    Returns descriptive text labels for the find flags \a flags.
+*/
 QString IFindFilter::descriptionForFindFlags(FindFlags flags)
 {
     QStringList flagStrings;

src/plugins/coreplugin/find/ifindsupport.cpp

@@ -30,6 +30,106 @@
 
 using namespace Core;
 
+/*!
+    \class Core::IFindSupport
+    \inmodule QtCreator
+    \brief The IFindSupport class provides functions for searching in a document
+     or widget.
+
+    \sa Core::BaseTextFind
+*/
+
+/*!
+    \enum IFindSupport::Result
+    This enum holds whether the search term was found within the search scope
+    using the find flags.
+
+    \value Found        The search term was found.
+    \value NotFound     The search term was not found.
+    \value NotYetFound  The search term has not been found yet.
+*/
+
+/*!
+    \fn IFindSupport::IFindSupport()
+    \internal
+*/
+
+/*!
+    \fn IFindSupport::~IFindSupport()
+    \internal
+*/
+
+/*!
+    \fn bool IFindSupport::supportsReplace() const
+    Returns whether the find filter supports search and replace.
+*/
+
+/*!
+    \fn FindFlags IFindSupport::supportedFindFlags() const
+    Returns the find flags, such as whole words or regular expressions,
+    that this find filter supports.
+
+    Depending on the returned value, the default find option widgets are
+    enabled or disabled.
+
+    The default is Core::FindBackward, Core::FindCaseSensitively,
+    Core::FindRegularExpression, Core::FindWholeWords, and
+    Core::FindPreserveCase.
+*/
+
+/*!
+    \fn void IFindSupport::resetIncrementalSearch()
+    Resets incremental search to start position.
+*/
+
+/*!
+    \fn void IFindSupport::clearHighlights()
+    Clears highlighting of search results in the searched widget.
+*/
+
+/*!
+    \fn QString IFindSupport::currentFindString() const
+    Returns the current search string.
+*/
+
+/*!
+    \fn QString IFindSupport::completedFindString() const
+    Returns the complete search string.
+*/
+
+/*!
+    \fn void IFindSupport::highlightAll(const QString &txt, FindFlags findFlags)
+    Highlights all search hits for \a txt when using \a findFlags.
+*/
+
+/*!
+    \fn Result IFindSupport::findIncremental(const QString &txt, FindFlags findFlags)
+    Performs an incremental search of the search term \a txt using \a findFlags.
+*/
+
+/*!
+    \fn Result IFindSupport::findStep(const QString &txt, FindFlags findFlags)
+    Searches for \a txt using \a findFlags.
+*/
+
+/*!
+    \fn void IFindSupport::defineFindScope()
+    Defines the find scope.
+*/
+
+/*!
+    \fn void IFindSupport::clearFindScope()
+    Clears the find scope.
+*/
+
+/*!
+    \fn void IFindSupport::changed()
+    This signal is emitted when the search changes.
+*/
+
+/*!
+    Replaces \a before with \a after as specified by \a findFlags.
+*/
 void IFindSupport::replace(const QString &before, const QString &after, FindFlags findFlags)
 {
     Q_UNUSED(before)
@@ -37,6 +137,12 @@ void IFindSupport::replace(const QString &before, const QString &after, FindFlag
     Q_UNUSED(findFlags)
 }
 
+/*!
+    Replaces \a before with \a after as specified by \a findFlags, and then
+    performs findStep().
+
+    Returns whether the find step found another match.
+*/
 bool IFindSupport::replaceStep(const QString &before, const QString &after, FindFlags findFlags)
 {
     Q_UNUSED(before)
@@ -45,6 +151,10 @@ bool IFindSupport::replaceStep(const QString &before, const QString &after, Find
     return false;
 }
 
+/*!
+    Finds and replaces all instances of \a before with \a after as specified by
+    \a findFlags.
+*/
 int IFindSupport::replaceAll(const QString &before, const QString &after, FindFlags findFlags)
 {
     Q_UNUSED(before)
@@ -53,6 +163,9 @@ int IFindSupport::replaceAll(const QString &before, const QString &after, FindFl
     return 0;
 }
 
+/*!
+    Shows \a parent overlayed with the wrap indicator.
+*/
 void IFindSupport::showWrapIndicator(QWidget *parent)
 {
     Utils::FadingIndicator::showPixmap(parent, Utils::StyleHelper::dpiSpecificImageFile(

src/plugins/coreplugin/find/itemviewfind.cpp

@@ -35,6 +35,12 @@
 
 namespace Core {
 
+/*!
+    \class Core::ItemViewFind
+    \inmodule QtCreator
+    \internal
+*/
+
 class ItemModelFindPrivate
 {
 public:

src/plugins/coreplugin/find/optionspopup.cpp

@@ -37,6 +37,12 @@
 
 namespace Core {
 
+/*!
+    \class Core::OptionsPopup
+    \inmodule QtCreator
+    \internal
+*/
+
 OptionsPopup::OptionsPopup(QWidget *parent, const QVector<Id> &commands)
     : QWidget(parent, Qt::Popup)
 {

src/plugins/coreplugin/find/searchresultwindow.cpp

@@ -53,6 +53,30 @@ static const int MAX_SEARCH_HISTORY = 12;
 
 namespace Core {
 
+/*!
+    \namespace Core::Search
+    \inmodule QtCreator
+    \internal
+*/
+
+/*!
+    \class Core::Search::TextPosition
+    \inmodule QtCreator
+    \internal
+*/
+
+/*!
+    \class Core::Search::TextRange
+    \inmodule QtCreator
+    \internal
+*/
+
+/*!
+    \class Core::SearchResultItem
+    \inmodule QtCreator
+    \internal
+*/
+
 namespace Internal {
 
     class InternalScrollArea : public QScrollArea
@@ -236,6 +260,7 @@ using namespace Core::Internal;
 
 /*!
     \class Core::SearchResult
+    \inmodule QtCreator
     \brief The SearchResult class reports user interaction, such as the
     activation of a search result item.
 
@@ -251,46 +276,99 @@ using namespace Core::Internal;
 */
 
 /*!
-    \fn void SearchResult::replaceButtonClicked(const QString &replaceText, const QList<Core::SearchResultItem> &checkedItems, bool preserveCase)
+    \fn void SearchResult::replaceButtonClicked(const QString &replaceText,
+                           const QList<Core::SearchResultItem> &checkedItems,
+                           bool preserveCase)
+
     Indicates that the user initiated a text replace by selecting
-    \gui {Replace All}, for example.
+    \uicontrol {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
+    the list of search result items that were selected by the user
-    in \a checkedItems.
+    in \a checkedItems, and whether a search and replace should preserve the
+    case of the replaced strings in \a preserveCase.
     The handler of this signal should apply the replace only on the selected
     items.
 */
 
+/*!
+    \enum Core::SearchResult::AddMode
+    This enum type specifies whether the search results should be sorted or
+    ordered:
+
+    \value AddSorted
+           The search results are sorted.
+    \value AddOrdered
+           The search results are ordered.
+*/
+
+/*!
+    \fn void SearchResult::cancelled()
+    This signal is emitted if the user cancels the search.
+*/
+
+/*!
+    \fn void SearchResult::countChanged(int count)
+    This signal is emitted when the number of search hits changes to \a count.
+*/
+
+/*!
+    \fn void SearchResult::paused(bool paused)
+    This signal is emitted when the search status is set to \a paused.
+*/
+
+/*!
+    \fn void SearchResult::requestEnabledCheck()
+
+    This signal is emitted when the enabled status of search results is
+    requested.
+*/
+
+/*!
+    \fn void SearchResult::searchAgainRequested()
+
+    This signal is emitted when the \uicontrol {Search Again} button is
+    selected.
+*/
+
+/*!
+    \fn void SearchResult::visibilityChanged(bool visible)
+
+    This signal is emitted when the visibility of the search results changes
+    to \a visible.
+*/
+
 /*!
     \class Core::SearchResultWindow
+    \inmodule QtCreator
     \brief The SearchResultWindow class is the implementation of a commonly
-    shared \gui{Search Results} output pane. Use it to show search results
+    shared \uicontrol{Search Results} output pane.
-    to a user.
+
+    \image qtcreator-searchresults.png
 
     Whenever you want to show the user a list of search results, or want
     to present UI for a global search and replace, use the single instance
     of this class.
 
-    Except for being an implementation of a output pane, the
+    In addition to being an implementation of an output pane, the
-    SearchResultWindow has a few functions and one enum that allows other
+    SearchResultWindow has functions and enums that enable other
     plugins to show their search results and hook into the user actions for
     selecting an entry and performing a global replace.
 
     Whenever you start a search, call startNewSearch(SearchMode) to initialize
-    the \gui {Search Results} output pane. The parameter determines if the GUI for
+    the \uicontrol {Search Results} output pane. The parameter determines if the GUI for
     replacing should be shown.
     The function 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
+    When you produce search results, call addResults() or addResult() to add them
-    to the \gui {Search Results} output pane.
+    to the \uicontrol {Search Results} output pane.
-    After the search has finished call finishSearch to inform the
+    After the search has finished call finishSearch() to inform the
-    \gui {Search Results} output pane about it.
+    \uicontrol {Search Results} output pane about it.
 
-    You will get activated signals via your SearchResult instance when
+    You will get activated() signals via your SearchResult instance when
-    the user selects a search result item, and, if you started the search
+    the user selects a search result item. If you started the search
-    with the SearchAndReplace option, the replaceButtonClicked signal
+    with the SearchAndReplace option, the replaceButtonClicked() signal
-    when the user requests a replace.
+    is emitted when the user requests a replace.
 */
 
 /*!
@@ -298,6 +376,17 @@ using namespace Core::Internal;
     \internal
 */
 
+/*!
+    \enum SearchResultWindow::PreserveCaseMode
+    This enum type specifies whether a search and replace should preserve the
+    case of the replaced strings:
+
+    \value PreserveCaseEnabled
+           The case is preserved when replacings strings.
+    \value PreserveCaseDisabled
+           The given case is used when replacing strings.
+*/
+
 SearchResultWindow *SearchResultWindow::m_instance = nullptr;
 
 /*!
@@ -322,7 +411,7 @@ SearchResultWindow::~SearchResultWindow()
 }
 
 /*!
-    Returns the single shared instance of the \gui {Search Results} output pane.
+    Returns the single shared instance of the \uicontrol {Search Results} output pane.
 */
 SearchResultWindow *SearchResultWindow::instance()
 {
@@ -356,24 +445,31 @@ QList<QWidget*> SearchResultWindow::toolBarWidgets() const
 }
 
 /*!
-    Tells the \gui {Search Results} output pane to start a new search.
+    Tells the \uicontrol {Search Results} output pane to start a new search.
 
     The \a label should be a string that shortly describes the type of the
     search, that is, the search filter and possibly the most relevant search
-     option, followed by a colon ':'. For example: \c {Project 'myproject':}
+    option, followed by a colon (:). For example: \c {Project 'myproject':}
     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.
+    The \a toolTip should elaborate on the search parameters, like file patterns
-    If \a cfgGroup is not empty, it will be used for storing the "do not ask again"
+    that are searched and find flags.
-    setting of a "this change cannot be undone" warning (which is implicitly requested
+
+    If \a cfgGroup is not empty, it will be used for storing the \e {do not ask again}
+    setting of a \e {this change cannot be undone} warning (which is implicitly requested
     by passing a non-empty group).
+
+    The \a searchOrSearchAndReplace parameter holds whether the search
+    results pane should show a UI for a global search and replace action.
+    The \a preserveCaseMode parameter holds whether the case of the search
+    string should be preserved when replacing strings.
+
     Returns a SearchResult object that is used for signaling user interaction
     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
+    and might delete it any time, even while the search is running.
-    (for example, when the user clears the \gui {Search Results} pane, or when
+    For example, when the user clears the \uicontrol {Search Results} pane, or when
-    the user opens so many other searches
+    the user opens so many other searches that this search falls out of the history.
-    that this search falls out of the history).
 
 */
 SearchResult *SearchResultWindow::startNewSearch(const QString &label,
@@ -420,7 +516,7 @@ SearchResult *SearchResultWindow::startNewSearch(const QString &label,
 }
 
 /*!
-    Clears the current contents of the \gui {Search Results} output pane.
+    Clears the current contents of the \uicontrol {Search Results} output pane.
 */
 void SearchResultWindow::clearContents()
 {
@@ -495,13 +591,18 @@ void SearchResultWindow::setTextEditorFont(const QFont &font,
         widget->setTextEditorFont(font, color);
 }
 
+/*!
+    Sets the \uicontrol {Search Results} tab width to \a tabWidth.
+*/
 void SearchResultWindow::setTabWidth(int tabWidth)
 {
     d->m_tabWidth = tabWidth;
     foreach (Internal::SearchResultWidget *widget, d->m_searchResultWidgets)
         widget->setTabWidth(tabWidth);
 }
-
+/*!
+    Opens a new search panel.
+*/
 void SearchResultWindow::openNewSearchPanel()
 {
     d->setCurrentIndexWithFocus(0);
@@ -644,23 +745,32 @@ QString SearchResult::textToReplace() const
     return m_widget->textToReplace();
 }
 
+/*!
+    Returns the number of search hits.
+*/
 int SearchResult::count() const
 {
     return m_widget->count();
 }
 
+/*!
+    Sets whether the \uicontrol {Seach Again} button is enabled to \a supported.
+*/
 void SearchResult::setSearchAgainSupported(bool supported)
 {
     m_widget->setSearchAgainSupported(supported);
 }
 
+/*!
+    Returns a UI for a global search and replace action.
+*/
 QWidget *SearchResult::additionalReplaceWidget() const
 {
     return m_widget->additionalReplaceWidget();
 }
 
 /*!
-    Adds a single result line to the \gui {Search Results} output pane.
+    Adds a single result line to the \uicontrol {Search Results} output pane.
 
     \a fileName, \a lineNumber, and \a lineText are shown on the result line.
     \a searchTermStart and \a searchTermLength specify the region that
@@ -683,6 +793,18 @@ void SearchResult::addResult(const QString &fileName, int lineNumber, const QStr
     m_widget->addResult(fileName, lineText, mainRange, userData);
 }
 
+/*!
+    Adds a single result line to the \uicontrol {Search Results} output pane.
+
+    \a mainRange specifies the region from the beginning of the search term
+    through its length that should be visually marked.
+    \a fileName and \a lineText are shown on the result line.
+    You can attach arbitrary \a userData to the search result, which can
+    be used, for example, when reacting to the signals of the search results
+    for your search.
+
+    \sa addResults()
+*/
 void SearchResult::addResult(const QString &fileName,
                              const QString &lineText,
                              Search::TextRange mainRange,
@@ -693,7 +815,8 @@ void SearchResult::addResult(const QString &fileName,
 }
 
 /*!
-    Adds the search result \a items to the \gui {Search Results} output pane.
+    Adds the search result \a items to the \uicontrol {Search Results} output
+    pane using \a mode.
 
     \sa addResult()
 */
@@ -704,8 +827,8 @@ void SearchResult::addResults(const QList<SearchResultItem> &items, AddMode mode
 }
 
 /*!
-    Notifies the \gui {Search Results} output pane that the current search
+    Notifies the \uicontrol {Search Results} output pane that the current search
-    has finished, and the UI should reflect that.
+    has been \a canceled, and the UI should reflect that.
 */
 void SearchResult::finishSearch(bool canceled)
 {
@@ -729,13 +852,16 @@ void SearchResult::restart()
     m_widget->restart();
 }
 
+/*!
+    Sets whether the \uicontrol {Seach Again} button is enabled to \a enabled.
+*/
 void SearchResult::setSearchAgainEnabled(bool enabled)
 {
     m_widget->setSearchAgainEnabled(enabled);
 }
 
 /*!
- * Opens the \gui {Search Results} output pane with this search.
+ * Opens the \uicontrol {Search Results} output pane with this search.
  */
 void SearchResult::popup()
 {

src/plugins/coreplugin/icore.cpp

@@ -44,6 +44,22 @@
     which constitute the basic functionality of \QC.
 */
 
+/*!
+    \enum Core::FindFlag
+    This enum holds the find flags.
+
+    \value FindBackward
+           Searches backwards.
+    \value FindCaseSensitively
+           Considers case when searching.
+    \value FindWholeWords
+           Finds only whole words.
+    \value FindRegularExpression
+           Uses a regular epression as a search term.
+    \value FindPreserveCase
+           Preserves the case when replacing search terms.
+*/
+
 /*!
     \namespace Core::Internal
     \internal
@@ -51,6 +67,7 @@
 
 /*!
     \class Core::ICore
+    \inmodule QtCreator
     \brief The ICore class allows access to the different parts that make up
     the basic functionality of \QC.
 
@@ -58,7 +75,7 @@
     instance is created by the Core plugin. You can access this instance
     from your plugin through \c{Core::instance()}.
 
-    \mainclass
+    \ingroup mainclasses
 */
 
 /*!
@@ -81,7 +98,7 @@
 /*!
     \fn bool ICore::showOptionsDialog(Id group, Id page, QWidget *parent = 0);
 
-    Opens the application \gui Options (or \gui Preferences) dialog with preselected
+    Opens the application \uicontrol Options (or \uicontrol Preferences) dialog with preselected
     \a page in the specified \a group.
 
     The arguments refer to the string IDs of the corresponding IOptionsPage.
@@ -230,7 +247,7 @@
     \fn void ICore::openFiles(const QStringList &fileNames, OpenFilesFlags flags = None)
     Opens all files from a list of \a fileNames like it would be
     done if they were given to \QC on the command line, or
-    they were opened via \gui File > \gui Open.
+    they were opened via \uicontrol File > \uicontrol Open.
 */
 
 /*!
@@ -253,12 +270,12 @@
     Signals that the user has requested that the global settings
     should be saved to disk.
 
-    At the moment that happens when the application is closed, and on \gui{Save All}.
+    At the moment that happens when the application is closed, and on \uicontrol{Save All}.
 */
 
 /*!
     \fn void ICore::optionsDialogRequested()
-    Enables plugins to perform actions just before the \gui Tools > \gui Options
+    Enables plugins to perform actions just before the \uicontrol Tools > \uicontrol Options
     dialog is shown.
 */