feedc0de/qt-creator
1
0
Fork 0
forked from qt-creator/qt-creator
Code Pull Requests Activity

Doc: edit find plugin API docs

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

Change-Id: I1f8c861f2f202f0af9056d639d6807b68ac517a2
Reviewed-by: Eike Ziller <eike.ziller@digia.com>
This commit is contained in:
Leena Miettinen
2013-09-09 10:46:07 +02:00
committed by Eike Ziller
parent 0c6636d291
commit 402447ffc9
2 changed files with 63 additions and 60 deletions
Download Patch File Download Diff File Expand all files Collapse all files

59
src/plugins/find/ifindfilter.cpp
View File

@@ -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}
dialog.
that are invoked by selecting \gui Edit > \gui {Find/Replace} >
\gui {Advanced Find}.
Implementations of this class add an additional "Scope" to the Advanced
Find dialog. That can be any search that requires the user to provide
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
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)
and "Files on File System" where the user provides a directory and file
scopes are \gui {All Projects} that searches from all files in all projects
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
to
If you want to implement a more specialized find filter, you need 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.
Always return a translatable string (i.e. use tr() for the return value).
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).
*/
/*!
\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
dialog with this filter/scope preselected.
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.
@@ -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()
\brief Signals that the enabled state of this find filter has changed.
\fn void IFindFilter::enabledChanged(bool enabled)
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

64
src/plugins/find/searchresultwindow.cpp
View File

@@ -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
\a item.
Indicates that the user activated the search result \a item by
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
all button.
Indicates that the user initiated a text replace by selecting
\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.
After the search has finished call finishSearch to inform the search
result window about it.
to the \gui {Search Results} output pane.
After the search has finished call finishSearch to inform the
\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
search, i.e. search filter and possibly a most relevant search option, followed by a colon ':'.
E.g. \code{Project 'myproject':}
The \a searchTerm will be shown behind the colon.
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':}
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
results window.
Adds the search result \a items to the \gui {Search Results} output pane.
\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()
{