From 8e84872ace9ccab8e9a3467d8bcce2e5cd0474d5 Mon Sep 17 00:00:00 2001 From: Leandro Melo 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 --- doc/api/qtcreator-api.qdoc | 8 ++++++ doc/api/qtcreator-api.qdocconf | 6 +++-- src/plugins/texteditor/basetexteditor.cpp | 12 +++++++++ .../texteditor/codeassist/iassistinterface.cpp | 23 +++++++++------- .../texteditor/codeassist/iassistprocessor.cpp | 8 +++--- .../texteditor/codeassist/iassistproposal.cpp | 31 ++++++++++++++++------ .../texteditor/codeassist/iassistproposalitem.cpp | 14 ++++++---- .../texteditor/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 574f64134c..707c653b82 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 1986dfa810..5ccca4b9df 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 d5a80b2168..c204d09a57 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 0fa73257ca..f612c56ee6 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 fff1c7ff7a..83014152b4 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 ba7a2fd514..e082f6c762 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 33d09d4c01..6b968fa2de 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 6222d5695e..ea353177c4 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 9c7cfef193..3394fb13cd 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 4e4cc8dccd..d96c5a63ef 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. */ -- 2.11.0