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

@@ -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
 */
 

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.

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;
 

src/plugins/texteditor/codeassist/iassistinterface.cpp

@@ -35,9 +35,10 @@
 using namespace TextEditor;
 
 /*!
-    \class IAssistInterface
+    \class TextEditor::IAssistInterface
-    \brief The IAssistInterface is an interface for providing access to the document from which
+    \brief The IAssistInterface class acts as an interface for providing access to the document
-    a proposal is computed.
+    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.
 */

src/plugins/texteditor/codeassist/iassistprocessor.cpp

@@ -35,8 +35,10 @@
 using namespace TextEditor;
 
 /*!
-    \class IAssistProcessor
+    \class TextEditor::IAssistProcessor
-    \brief The IAssistProcessor is an interface that actually computes an assist proposal.
+    \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.

src/plugins/texteditor/codeassist/iassistproposal.cpp

@@ -35,8 +35,21 @@
 using namespace TextEditor;
 
 /*!
-    \class IAssistProposal
+    \group CodeAssist
-    \brief The IAssistProposal is an interface for representing an assist proposal.
+    \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,

src/plugins/texteditor/codeassist/iassistproposalitem.cpp

@@ -35,8 +35,12 @@
 using namespace TextEditor;
 
 /*!
-    \class IAssistProposalItem
+    \class TextEditor::IAssistProposalItem
-    \brief The IAssistProposalItem is an interface for representing an assist proposal item.
+    \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.
 */

src/plugins/texteditor/codeassist/iassistproposalmodel.cpp

@@ -35,14 +35,17 @@
 using namespace TextEditor;
 
 /*!
-    \class IAssistProposalModel
+    \class TextEditor::IAssistProposalModel
-    \brief The IAssistProposalModel is an interface for representing proposals.
+    \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()

src/plugins/texteditor/codeassist/iassistproposalwidget.cpp

@@ -35,8 +35,10 @@
 using namespace TextEditor;
 
 /*!
-    \class IAssistProposalWidget
+    \class TextEditor::IAssistProposalWidget
-    \brief The IAssistProposalWidget is an interface for widgets that display assist proposals.
+    \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.
 */

src/plugins/texteditor/codeassist/iassistprovider.cpp

@@ -35,8 +35,9 @@
 using namespace TextEditor;
 
 /*!
-    \class IAssistProvider
+    \class TextEditor::IAssistProvider
-    \brief The IAssistProvider is an interface for providing code assist.
+    \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.
 */