Commit 8e84872a authored by Leandro Melo's avatar Leandro Melo Committed by Friedemann Kleint

Documentation: Code assist API

Change-Id: Id703725708823edc24171f7c1b28befe99032d63
Reviewed-on: http://codereview.qt.nokia.com/154Reviewed-by: default avatarFriedemann Kleint <Friedemann.Kleint@nokia.com>
parent 5647e677
......@@ -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
*/
......
......@@ -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.
......
......@@ -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;
......
......@@ -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.
*/
......@@ -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.
......
......@@ -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,
......
......@@ -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.
*/
......@@ -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()
......
......@@ -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.
*/
......@@ -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.
*/
Markdown is supported
0% or
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment