From 8e84872ace9ccab8e9a3467d8bcce2e5cd0474d5 Mon Sep 17 00:00:00 2001
From: Leandro Melo <leandro.melo@nokia.com>
Date: Thu, 26 May 2011 18:09:17 +0200
Subject: [PATCH] Documentation: Code assist API
Change-Id: Id703725708823edc24171f7c1b28befe99032d63
Reviewed-on: http://codereview.qt.nokia.com/154
Reviewed-by: Friedemann Kleint <Friedemann.Kleint@nokia.com>
---
doc/api/qtcreator-api.qdoc | 8 +++++
doc/api/qtcreator-api.qdocconf | 6 ++--
src/plugins/texteditor/basetexteditor.cpp | 12 +++++++
.../codeassist/iassistinterface.cpp | 23 ++++++++------
.../codeassist/iassistprocessor.cpp | 8 +++--
.../texteditor/codeassist/iassistproposal.cpp | 31 ++++++++++++++-----
.../codeassist/iassistproposalitem.cpp | 14 ++++++---
.../codeassist/iassistproposalmodel.cpp | 7 +++--
.../codeassist/iassistproposalwidget.cpp | 30 ++++++++++--------
.../texteditor/codeassist/iassistprovider.cpp | 11 ++++---
10 files changed, 103 insertions(+), 47 deletions(-)
diff --git a/doc/api/qtcreator-api.qdoc b/doc/api/qtcreator-api.qdoc
index 574f64134cc..707c653b822 100644
--- a/doc/api/qtcreator-api.qdoc
+++ b/doc/api/qtcreator-api.qdoc
@@ -70,6 +70,7 @@
\o \l{qtcreatorcdbext}
\o Windows CDB debugger extension
+
\endtable
\section1 Plugins
@@ -110,6 +111,13 @@
\o \l{VCSBase}
\o Base classes for version control support.
+ \row
+ \o \l{TextEditor}
+ \o This is where everything starts if you want to create a text editor. Besides
+ the base editor itself, this plugin contains APIs for supporting functionality
+ like snippets, highlighting, \l{CodeAssist}{code assist}, indentation and style,
+ and others.
+
\endtable
*/
diff --git a/doc/api/qtcreator-api.qdocconf b/doc/api/qtcreator-api.qdocconf
index 1986dfa810c..5ccca4b9dfa 100644
--- a/doc/api/qtcreator-api.qdocconf
+++ b/doc/api/qtcreator-api.qdocconf
@@ -16,7 +16,8 @@ headerdirs = . \
../../src/plugins/locator \
../../src/plugins/debugger \
../../src/plugins/vcsbase \
- ../../src/plugins/projectexplorer
+ ../../src/plugins/projectexplorer \
+ ../../src/plugins/texteditor
sourcedirs = . \
../../src/libs/aggregation \
@@ -29,7 +30,8 @@ sourcedirs = . \
../../src/plugins/locator \
../../src/plugins/debugger \
../../src/plugins/vcsbase \
- ../../src/plugins/projectexplorer
+ ../../src/plugins/projectexplorer \
+ ../../src/plugins/texteditor
# -- Generate complete documentation. Set this to 'false'
# to generate public API documentation only.
diff --git a/src/plugins/texteditor/basetexteditor.cpp b/src/plugins/texteditor/basetexteditor.cpp
index d5a80b21681..c204d09a57a 100644
--- a/src/plugins/texteditor/basetexteditor.cpp
+++ b/src/plugins/texteditor/basetexteditor.cpp
@@ -98,6 +98,18 @@
//#define DO_FOO
+/*!
+ \namespace TextEditor
+ \brief The TextEditor namespace contains the base text editor and several classes which
+ provide supporting functionality like snippets, highlighting, \l{CodeAssist}{code assist},
+ indentation and style, and others.
+*/
+
+/*!
+ \namespace TextEditor::Internal
+ \internal
+*/
+
using namespace TextEditor;
using namespace TextEditor::Internal;
diff --git a/src/plugins/texteditor/codeassist/iassistinterface.cpp b/src/plugins/texteditor/codeassist/iassistinterface.cpp
index 0fa73257ca2..f612c56ee68 100644
--- a/src/plugins/texteditor/codeassist/iassistinterface.cpp
+++ b/src/plugins/texteditor/codeassist/iassistinterface.cpp
@@ -35,9 +35,10 @@
using namespace TextEditor;
/*!
- \class IAssistInterface
- \brief The IAssistInterface is an interface for providing access to the document from which
- a proposal is computed.
+ \class TextEditor::IAssistInterface
+ \brief The IAssistInterface class acts as an interface for providing access to the document
+ from which a proposal is computed.
+ \ingroup CodeAssist
This interface existis in order to avoid a direct dependency on the text editor. This is
particularly important and safer for asynchronous providers, since in such cases computation
@@ -47,6 +48,8 @@ using namespace TextEditor;
This is in order to make the design a bit more generic and allow code assist to be
pluggable into different types of documents (there are still issues to be treated).
+ This class is part of the CodeAssist API.
+
\sa IAssistProposal, IAssistProvider, IAssistProcessor
*/
@@ -57,36 +60,36 @@ IAssistInterface::~IAssistInterface()
{}
/*!
- \fn int position() const
+ \fn int TextEditor::IAssistInterface::position() const
Returns the cursor position.
*/
/*!
- \fn QChar characterAt(int position) const
+ \fn QChar TextEditor::IAssistInterface::characterAt(int position) const
Returns the character at \a position.
*/
/*!
- \fn QString textAt(int position, int length) const
+ \fn QString TextEditor::IAssistInterface::textAt(int position, int length) const
Returns the text at \a position with the given \a length.
*/
/*!
- \fn const Core::IFile *file() const
+ \fn const Core::IFile *TextEditor::IAssistInterface::file() const
Returns the file associated.
*/
/*!
- \fn QTextDocument *document() const
+ \fn QTextDocument *TextEditor::IAssistInterface::document() const
Returns the document.
*/
/*!
- \fn void detach(QThread *destination)
+ \fn void TextEditor::IAssistInterface::detach(QThread *destination)
Detaches the interface. If it is necessary to take any special care in order to allow
this interface to be run in a separate thread \a destination this needs to be done
@@ -94,7 +97,7 @@ IAssistInterface::~IAssistInterface()
*/
/*!
- \fn AssistReason reason() const
+ \fn AssistReason TextEditor::IAssistInterface::reason() const
The reason which triggered the assist.
*/
diff --git a/src/plugins/texteditor/codeassist/iassistprocessor.cpp b/src/plugins/texteditor/codeassist/iassistprocessor.cpp
index fff1c7ff7ac..83014152b46 100644
--- a/src/plugins/texteditor/codeassist/iassistprocessor.cpp
+++ b/src/plugins/texteditor/codeassist/iassistprocessor.cpp
@@ -35,8 +35,10 @@
using namespace TextEditor;
/*!
- \class IAssistProcessor
- \brief The IAssistProcessor is an interface that actually computes an assist proposal.
+ \class TextEditor::IAssistProcessor
+ \brief The IAssistProcessor class acts as an interface that actually computes an assist
+ proposal.
+ \ingroup CodeAssist
\sa IAssistProposal, IAssistProvider
*/
@@ -48,7 +50,7 @@ IAssistProcessor::~IAssistProcessor()
{}
/*!
- \fn IAssistProposal *perform(const IAssistInterface *interface)
+ \fn IAssistProposal *TextEditor::IAssistProcessor::perform(const IAssistInterface *interface)
Computes a proposal and returns it. Access to the document is made through the \a interface.
If this is an asynchronous processor the \a interface will be detached.
diff --git a/src/plugins/texteditor/codeassist/iassistproposal.cpp b/src/plugins/texteditor/codeassist/iassistproposal.cpp
index ba7a2fd5140..e082f6c762f 100644
--- a/src/plugins/texteditor/codeassist/iassistproposal.cpp
+++ b/src/plugins/texteditor/codeassist/iassistproposal.cpp
@@ -35,8 +35,21 @@
using namespace TextEditor;
/*!
- \class IAssistProposal
- \brief The IAssistProposal is an interface for representing an assist proposal.
+ \group CodeAssist
+ \title Code Assist for Editors
+
+ These classes are used to provide code assist support such as completions and refactoring
+ actions for editors.
+
+ Completions can be of a variety of kind like function hints, snippets, and regular
+ context-aware content. The later are usually represented by semantic proposals, but
+ it is also possible that they are simply plain text as supported in the fake vim mode.
+*/
+
+/*!
+ \class TextEditor::IAssistProposal
+ \brief The IAssistProposal class acts as an interface for representing an assist proposal.
+ \ingroup CodeAssist
Known implenters of this interface are FunctionHintProposal and GenericProposal. The
former is recommended to be used when assisting function call constructs (overloads
@@ -44,6 +57,8 @@ using namespace TextEditor;
snippets, refactoring operations (quickfixes), and contextual content (the member of
class or a string existent in the document, for example).
+ This class is part of the CodeAssist API.
+
\sa IAssistProposalWidget, IAssistModel
*/
@@ -54,7 +69,7 @@ IAssistProposal::~IAssistProposal()
{}
/*!
- \fn bool isFragile() const
+ \fn bool TextEditor::IAssistProposal::isFragile() const
Returns whether this is a fragile proposal. When a proposal is fragile it means that
it will be replaced by a new proposal in the case one is created, even if due to an
@@ -62,13 +77,13 @@ IAssistProposal::~IAssistProposal()
*/
/*!
- \fn int basePosition() const
+ \fn int TextEditor::IAssistProposal::basePosition() const
Returns the position from which this proposal starts.
*/
/*!
- \fn bool isCorrective() const
+ \fn bool TextEditor::IAssistProposal::isCorrective() const
Returns whether this proposal is also corrective. This could happen in C++, for example,
when a dot operator (.) needs to be replaced by an arrow operator (->) before the proposal
@@ -76,13 +91,13 @@ IAssistProposal::~IAssistProposal()
*/
/*!
- \fn void makeCorrection(BaseTextEditor *editor)
+ \fn void TextEditor::IAssistProposal::makeCorrection(BaseTextEditor *editor)
This allows a correction to be made in the case this is a corrective proposal.
*/
/*!
- \fn IAssistModel *model() const
+ \fn IAssistModel *TextEditor::IAssistProposal::model() const
Returns the model associated with this proposal.
@@ -93,7 +108,7 @@ IAssistProposal::~IAssistProposal()
*/
/*!
- \fn IAssistProposalWidget *createWidget() const
+ \fn IAssistProposalWidget *TextEditor::IAssistProposal::createWidget() const
Returns the widget associated with this proposal. The IAssistProposalWidget implementor
recommended for function hint proposals is FunctionHintProposalWidget. For snippets,
diff --git a/src/plugins/texteditor/codeassist/iassistproposalitem.cpp b/src/plugins/texteditor/codeassist/iassistproposalitem.cpp
index 33d09d4c01a..6b968fa2dec 100644
--- a/src/plugins/texteditor/codeassist/iassistproposalitem.cpp
+++ b/src/plugins/texteditor/codeassist/iassistproposalitem.cpp
@@ -35,8 +35,12 @@
using namespace TextEditor;
/*!
- \class IAssistProposalItem
- \brief The IAssistProposalItem is an interface for representing an assist proposal item.
+ \class TextEditor::IAssistProposalItem
+ \brief The IAssistProposalItem class acts as an interface for representing an assist
+ proposal item.
+ \ingroup CodeAssist
+
+ This is class is part of the CodeAssist API.
*/
IAssistProposalItem::IAssistProposalItem()
@@ -46,20 +50,20 @@ IAssistProposalItem::~IAssistProposalItem()
{}
/*!
- \fn bool implicitlyApplies() const
+ \fn bool TextEditor::IAssistProposalItem::implicitlyApplies() const
Returns whether this item should implicitly apply in the case it is the only proposal
item available.
*/
/*!
- \fn bool prematurelyApplies(const QChar &c) const
+ \fn bool TextEditor::IAssistProposalItem::prematurelyApplies(const QChar &c) const
Returns whether the character \a c causes this item to be applied.
*/
/*!
- \fn void apply(BaseTextEditor *editor, int basePosition) const
+ \fn void TextEditor::IAssistProposalItem::apply(BaseTextEditor *editor, int basePosition) const
This is the place to implement the actual application of the item.
*/
diff --git a/src/plugins/texteditor/codeassist/iassistproposalmodel.cpp b/src/plugins/texteditor/codeassist/iassistproposalmodel.cpp
index 6222d5695ec..ea353177c41 100644
--- a/src/plugins/texteditor/codeassist/iassistproposalmodel.cpp
+++ b/src/plugins/texteditor/codeassist/iassistproposalmodel.cpp
@@ -35,14 +35,17 @@
using namespace TextEditor;
/*!
- \class IAssistProposalModel
- \brief The IAssistProposalModel is an interface for representing proposals.
+ \class TextEditor::IAssistProposalModel
+ \brief The IAssistProposalModel class acts as an interface for representing proposals.
+ \ingroup CodeAssist
Known implenters of this interface are IFunctionHintProposalModel and IGenericProposalModel.
The former is recommeded to be used when assisting function calls constructs (overloads
and parameters) while the latter is quite generic so that it could be used to propose
snippets, refactoring operations (quickfixes), and contextual content (the member of class
or a string existent in the document, for example).
+
+ This is class is part of the CodeAssist API.
*/
IAssistProposalModel::IAssistProposalModel()
diff --git a/src/plugins/texteditor/codeassist/iassistproposalwidget.cpp b/src/plugins/texteditor/codeassist/iassistproposalwidget.cpp
index 9c7cfef1930..3394fb13cd9 100644
--- a/src/plugins/texteditor/codeassist/iassistproposalwidget.cpp
+++ b/src/plugins/texteditor/codeassist/iassistproposalwidget.cpp
@@ -35,8 +35,10 @@
using namespace TextEditor;
/*!
- \class IAssistProposalWidget
- \brief The IAssistProposalWidget is an interface for widgets that display assist proposals.
+ \class TextEditor::IAssistProposalWidget
+ \brief The IAssistProposalWidget class acts as an interface for widgets that display
+ assist proposals.
+ \ingroup CodeAssist
Known implenters of this interface are FunctionHintProposalWidget and GenericProposalWidget.
The former is recommeded to be used when assisting function calls constructs (overloads
@@ -48,6 +50,8 @@ using namespace TextEditor;
This is in order to make the design a bit more generic and allow code assist to be
pluggable into different types of documents (there are still issues to be treated).
+ This is class is part of the CodeAssist API.
+
\sa IAssistProposal
*/
@@ -59,38 +63,38 @@ IAssistProposalWidget::~IAssistProposalWidget()
{}
/*!
- \fn void setAssistant(CodeAssistant *assistant)
+ \fn void TextEditor::IAssistProposalWidget::setAssistant(CodeAssistant *assistant)
Sets the code assistant which is the owner of this widget. This is used so that the code
assistant can be notified when changes on the underlying widget happen.
*/
/*!
- \fn void setReason(AssistReason reason)
+ \fn void TextEditor::IAssistProposalWidget::setReason(AssistReason reason)
Sets the reason which triggered the assist.
*/
/*!
- \fn void setUnderlyingWidget(const QWidget *underlyingWidget)
+ \fn void TextEditor::IAssistProposalWidget::setUnderlyingWidget(const QWidget *underlyingWidget)
Sets the underlying widget upon which this proposal operates.
*/
/*!
- \fn void setModel(IAssistModel *model)
+ \fn void TextEditor::IAssistProposalWidget::setModel(IAssistModel *model)
Sets the model.
*/
/*!
- \fn void setDisplayRect(const QRect &rect)
+ \fn void TextEditor::IAssistProposalWidget::setDisplayRect(const QRect &rect)
Sets the \a rect on which this widget should be displayed.
*/
/*!
- \fn void showProposal(const QString &prefix)
+ \fn void TextEditor::IAssistProposalWidget::showProposal(const QString &prefix)
Shows the proposal. The \a prefix is the string comprised from the character at the base
position of the proposal until the character immediately after the cursor at the moment
@@ -100,7 +104,7 @@ IAssistProposalWidget::~IAssistProposalWidget()
*/
/*!
- \fn virtual void updateProposal(const QString &prefix)
+ \fn void TextEditor::IAssistProposalWidget::updateProposal(const QString &prefix)
Updates the proposal base on the give \a prefix.
@@ -108,13 +112,13 @@ IAssistProposalWidget::~IAssistProposalWidget()
*/
/*!
- \fn void closeProposal()
+ \fn void TextEditor::IAssistProposalWidget::closeProposal()
Closes the proposal.
*/
/*!
- \fn void setIsSynchronized(bool isSync)
+ \fn void TextEditor::IAssistProposalWidget::setIsSynchronized(bool isSync)
Sets whether this widget is synchronized. If a widget is synchronized it means that from
the moment a proposal started being computed until the moment it is actually displayed,
@@ -126,7 +130,7 @@ IAssistProposalWidget::~IAssistProposalWidget()
*/
/*!
- \fn void prefixExpanded(const QString &newPrefix)
+ \fn void TextEditor::IAssistProposalWidget::prefixExpanded(const QString &newPrefix)
The signal is emitted whenever this widget automatically expands the prefix of the proposal.
This can happen if all available proposal items share the same prefix and if the proposal's
@@ -136,7 +140,7 @@ IAssistProposalWidget::~IAssistProposalWidget()
*/
/*!
- void proposalItemActivated(IAssistProposalItem *proposalItem)
+ \fn void TextEditor::IAssistProposalWidget::proposalItemActivated(IAssistProposalItem *proposalItem)
This signal is emitted whenever \a proposalItem is chosen to be applied.
*/
diff --git a/src/plugins/texteditor/codeassist/iassistprovider.cpp b/src/plugins/texteditor/codeassist/iassistprovider.cpp
index 4e4cc8dccdd..d96c5a63efd 100644
--- a/src/plugins/texteditor/codeassist/iassistprovider.cpp
+++ b/src/plugins/texteditor/codeassist/iassistprovider.cpp
@@ -35,8 +35,9 @@
using namespace TextEditor;
/*!
- \class IAssistProvider
- \brief The IAssistProvider is an interface for providing code assist.
+ \class TextEditor::IAssistProvider
+ \brief The IAssistProvider class acts as an interface for providing code assist.
+ \ingroup CodeAssist
There might be different kinds of assist such as completions or refactoring
actions (quickfixes).
@@ -46,6 +47,8 @@ using namespace TextEditor;
Examples of completions currently supported are snippets, function hints, and
contextual contents.
+ This is class is part of the CodeAssist API.
+
\sa IAssistProposal, IAssistProcessor
*/
@@ -56,13 +59,13 @@ IAssistProvider::~IAssistProvider()
{}
/*!
- \fn bool supportsEditor(const QString &editorId) const
+ \fn bool TextEditor::IAssistProvider::supportsEditor(const QString &editorId) const
Returns whether this provider supports the editor which has the give \a editorId.
*/
/*!
- \fn IAssistProcessor *createProcessor() const
+ \fn IAssistProcessor *TextEditor::IAssistProvider::createProcessor() const
Creates and returns the IAssistProcessor responsible for computing an IAssistProposal.
*/
--
GitLab