API Documentation: Add VCSBase.

doc/api/qtcreator-api.qdoc

@@ -108,6 +108,10 @@
     \o \l{Debugger}
     \o Debugging functionality.
 
+    \row
+    \o \l{VCSBase}
+    \o Base classes for version control support.
+
     \endtable
 */
 

doc/api/qtcreator-api.qdocconf

@@ -14,7 +14,8 @@ headerdirs              = . \
                           ../../src/plugins/coreplugin \
                           ../../src/plugins/find \
                           ../../src/plugins/locator \
-                          ../../src/plugins/debugger
+                          ../../src/plugins/debugger \
+                          ../../src/plugins/vcsbase
 
 sourcedirs              = . \
                           ../../src/libs/aggregation \
@@ -25,7 +26,8 @@ sourcedirs              = . \
                           ../../src/plugins/coreplugin \
                           ../../src/plugins/find \
                           ../../src/plugins/locator \
-                         ../../src/plugins/debugger
+                          ../../src/plugins/debugger \
+                          ../../src/plugins/vcsbase
 
 # -- Generate complete documentation. Set this to 'false'
 #    to generate public API documentation only.

src/plugins/vcsbase/baseannotationhighlighter.cpp

@@ -43,6 +43,19 @@
 
 typedef QMap<QString, QTextCharFormat> ChangeNumberFormatMap;
 
+/*!
+    \class VCSBase::BaseAnnotationHighlighter
+
+    \brief Base for a highlighter for annotation lines of the form 'changenumber:XXXX'.
+
+    The change numbers are assigned a color gradient. Example:
+    \code
+    112: text1 <color 1>
+    113: text2 <color 2>
+    112: text3 <color 1>
+    \endcode
+*/
+
 namespace VCSBase {
 
 struct BaseAnnotationHighlighterPrivate {

src/plugins/vcsbase/baseannotationhighlighter.h

@@ -42,12 +42,6 @@ namespace VCSBase {
 
 struct BaseAnnotationHighlighterPrivate;
 
-// Base for a highlighter for annotation lines of the form
-// 'changenumber:XXXX'. The change numbers are assigned a color gradient.
-// Example:
-// 112: text1 <color 1>
-// 113: text2 <color 2>
-// 112: text3 <color 1>
 class VCSBASE_EXPORT BaseAnnotationHighlighter : public TextEditor::SyntaxHighlighter
 {
     Q_OBJECT

src/plugins/vcsbase/basecheckoutwizard.cpp

@@ -43,6 +43,27 @@
 #include <QtCore/QDir>
 #include <QtGui/QMessageBox>
 
+/*!
+    \class VCSBase::BaseCheckoutWizard
+
+    \brief A Core::IWizard implementing a wizard for initially checking out a project using
+    a version control system.
+
+   Implements all of Core::IWizard with the exception of
+   name()/description() and icon().
+
+   Pops up a QWizard consisting of a Parameter Page which is created
+   by a virtual factory function and a progress
+   page containing a log text. The factory function createJob()
+   creates a job with the output connected to the log window,
+   returning the path to the checkout.
+
+   On success, the wizard tries to locate a project file
+   and open it.
+
+   \sa VCSBase::BaseCheckoutWizardPage
+*/
+
 namespace VCSBase {
 
 struct BaseCheckoutWizardPrivate {

src/plugins/vcsbase/basecheckoutwizard.h

@@ -49,20 +49,6 @@ namespace VCSBase {
 class AbstractCheckoutJob;
 struct BaseCheckoutWizardPrivate;
 
-/* A Core::IWizard implementing a wizard for initially checking
- * out a project using a version control system.
- * Implements all of Core::IWizard with the exception of
- * name()/description() and icon().
- * Pops up a QWizard consisting of a Parameter Page which is created
- * by a virtual factory function and a progress
- * page containing a log text. The factory function createJob()
- * creates a job with the output connected to the log window,
- * returning the path to the checkout.
- * On success, the wizard tries to locate a project file
- * and open it.
- * BaseCheckoutWizardPage is provided as a convenience base class
- * for parameter wizard pages. */
-
 class VCSBASE_EXPORT BaseCheckoutWizard : public Core::IWizard
 {
     Q_OBJECT

src/plugins/vcsbase/basecheckoutwizardpage.cpp

@@ -36,6 +36,18 @@
 
 #include <QtGui/QIcon>
 
+/*!
+    \class VCSBase::BaseCheckoutWizardPage
+
+    \brief Base class for a parameter page of a checkout wizard.
+
+    Lets the user specify the repository, a checkout directory and
+    the path. Contains a virtual to derive the checkout directory
+    from the repository as it is entered.
+
+    \sa VCSBase::BaseCheckoutWizard
+*/
+
 namespace VCSBase {
 
 struct BaseCheckoutWizardPagePrivate {

src/plugins/vcsbase/basecheckoutwizardpage.h

@@ -46,11 +46,6 @@ namespace Ui {
 
 struct BaseCheckoutWizardPagePrivate;
 
-/* Base class for a parameter page of a checkout wizard.
- * Let's the user specify the repository, a checkout directory and
- * the path. Contains a virtual to derive the checkout directory
- * from the repository as it is entered. */
-
 class VCSBASE_EXPORT BaseCheckoutWizardPage : public QWizardPage {
     Q_OBJECT
     Q_PROPERTY(bool isBranchSelectorVisible READ isBranchSelectorVisible WRITE setBranchSelectorVisible)

src/plugins/vcsbase/basevcseditorfactory.cpp

@@ -41,6 +41,14 @@
 
 #include <QtCore/QCoreApplication>
 
+/*!
+    \class VCSBase::BaseVCSEditorFactory
+
+    \brief Base class for editor factories creating instances of VCSBaseEditor subclasses.
+
+    \sa VCSBase::VCSBaseEditorWidget
+*/
+
 namespace VCSBase {
 
 struct BaseVCSEditorFactoryPrivate

src/plugins/vcsbase/basevcseditorfactory.h

@@ -45,8 +45,6 @@ namespace VCSBase {
 
 struct BaseVCSEditorFactoryPrivate;
 
-// Base class for editor factories creating instances of VCSBaseEditor
-//  subclasses.
 class VCSBASE_EXPORT BaseVCSEditorFactory : public Core::IEditorFactory
 {
     Q_OBJECT

src/plugins/vcsbase/checkoutjobs.cpp

@@ -43,6 +43,16 @@
 #include <utils/qtcassert.h>
 
 enum { debug = 0 };
+
+/*!
+    \class  VCSBase::AbstractCheckoutJob
+
+    \brief Abstract base class for a job creating an initial project checkout.
+           It should be something that runs in the background producing log messages.
+
+    \sa VCSBase::BaseCheckoutWizard
+*/
+
 namespace VCSBase {
 
 AbstractCheckoutJob::AbstractCheckoutJob(QObject *parent) :
@@ -82,6 +92,12 @@ static inline QSharedPointer<QProcess> createProcess()
     return Utils::SynchronousProcess::createProcess(flags);
 }
 
+/*!
+    \class VCSBase::ProcessCheckoutJob
+
+    \brief Convenience implementation of a VCSBase::AbstractCheckoutJob using a QProcess.
+*/
+
 ProcessCheckoutJobPrivate::ProcessCheckoutJobPrivate() :
     process(createProcess())
 {    

src/plugins/vcsbase/checkoutjobs.h

@@ -70,8 +70,6 @@ signals:
     void output(const QString &what);
 };
 
-/* Convenience implementation using a QProcess. */
-
 class VCSBASE_EXPORT ProcessCheckoutJob : public AbstractCheckoutJob
 {
     Q_OBJECT

src/plugins/vcsbase/checkoutprogresswizardpage.cpp

@@ -40,6 +40,15 @@
 #include <QtGui/QApplication>
 #include <QtGui/QCursor>
 
+/*!
+    \class VCSBase::CheckoutProgressWizardPage
+
+    \brief Page showing the progress of an initial project checkout. Turns complete when the job
+           succeeds.
+
+    \sa VCSBase::BaseCheckoutWizard
+*/
+
 namespace VCSBase {
 namespace Internal {
 

src/plugins/vcsbase/checkoutprogresswizardpage.h

@@ -46,9 +46,6 @@ namespace Ui {
     class CheckoutProgressWizardPage;
 }
 
-/* Page showing the progress of an initial project
- * checkout. Turns complete when the job succeeds. */
-
 class CheckoutProgressWizardPage : public QWizardPage {
     Q_OBJECT
     Q_DISABLE_COPY(CheckoutProgressWizardPage)

src/plugins/vcsbase/checkoutwizarddialog.cpp

@@ -40,6 +40,13 @@
 
 #include <QtGui/QPushButton>
 
+/*!
+    \class VCSBase::Internal::CheckoutWizardDialog
+
+    Dialog used by \sa VCSBase::BaseCheckoutWizard. Overwrites reject() to first
+    kill the checkout and then close.
+ */
+
 namespace VCSBase {
 namespace Internal {
 

src/plugins/vcsbase/checkoutwizarddialog.h

@@ -44,10 +44,6 @@ class AbstractCheckoutJob;
 namespace Internal {
 class CheckoutProgressWizardPage;
 
-/* See BaseCheckoutWizard.
- * Overwrites reject() to first kill the checkout
- * and then close. */
-
 class CheckoutWizardDialog : public Utils::Wizard {
     Q_OBJECT
 public:

src/plugins/vcsbase/cleandialog.cpp

@@ -53,6 +53,17 @@
 #include <QtCore/QFuture>
 #include <QtCore/QtConcurrentRun>
 
+/*!
+    \class VCSBase::CleanDialog
+
+    \brief File selector dialog for files not under version control.
+
+    Completely clean a directory under version control
+    from all files that are not under version control based on a list
+    generated from the version control system. Presents the user with
+    a checkable list of files and/or directories. Double click opens a file.
+*/
+
 enum { nameColumn, columnCount };
 enum { fileNameRole = Qt::UserRole, isDirectoryRole = Qt::UserRole + 1 };
 

src/plugins/vcsbase/cleandialog.h

@@ -45,11 +45,6 @@ QT_END_NAMESPACE
 namespace VCSBase {
 struct CleanDialogPrivate;
 
-/* CleanDialog: Completely clean a directory under version control
- * from all files that are not under version control based on a list
- * generated from the version control system. Presents the user with
- * a checkable list of files and/or directories. Double click opens a file. */
-
 class VCSBASE_EXPORT CleanDialog : public QDialog {
     Q_OBJECT
 public:

src/plugins/vcsbase/corelistener.cpp

@@ -34,6 +34,17 @@
 #include "corelistener.h"
 #include "vcsbasesubmiteditor.h"
 
+/*!
+    \class VCSBase::Internal::CoreListener
+
+    \brief CoreListener catching closing of a submit editor.
+
+    Catch the closing of a submit editor to trigger the submit.
+    One instance of this class exists, connected to the instances
+    of VCSBasePlugin, which dispatch if the editor kind matches theirs
+    (which is why the approach of passing the bool result was chosen).
+*/
+
 namespace VCSBase {
 namespace Internal {
 

src/plugins/vcsbase/corelistener.h

@@ -42,11 +42,6 @@ class VCSBaseSubmitEditor;
 
 namespace Internal {
 
-// Catch the closing of a submit editor to trigger the submit.
-// One instance of this class exists, connected to the instances
-// of VCSBasePlugin, which dispatch if the editor kind matches theirs
-// (which is why the approach of passing the bool result was chosen).
-
 class CoreListener : public Core::ICoreListener
 {
     Q_OBJECT
@@ -58,6 +53,6 @@ signals:
     void submitEditorAboutToClose(VCSBaseSubmitEditor *e, bool *result);
 };
 
-}
+} // Internal
-}
+} // VCSBase
 #endif // CORELISTENER_H

src/plugins/vcsbase/diffhighlighter.cpp

@@ -42,6 +42,28 @@
 #include <QtCore/QRegExp>
 #include <QtGui/QBrush>
 
+/*!
+    \class VCSBase::DiffHighlighter
+
+    \brief A highlighter for diffs.
+
+    Parametrizable by the file indicator, which is for example '^====' in case of p4:
+    \code
+    ==== //depot/research/main/qdynamicmainwindow3/qdynamicdockwidgetlayout_p.h#34 (text) ====
+    \endcode
+
+    Or  '--- a/|'+++ b/' in case of git:
+    \code
+    diff --git a/src/plugins/plugins.pro b/src/plugins/plugins.pro
+    index 9401ee7..ef35c3b 100644
+    --- a/src/plugins/plugins.pro
+    +++ b/src/plugins/plugins.pro
+    @@ -10,6 +10,7 @@ SUBDIRS   = plugin_coreplugin
+    \endcode
+
+    Also highlights trailing blanks.
+ */
+
 static const int BASE_LEVEL = 0;
 static const int FILE_LEVEL = 1;
 static const int LOCATION_LEVEL = 2;

src/plugins/vcsbase/diffhighlighter.h

@@ -56,21 +56,6 @@ namespace Internal {
 class DiffHighlighterPrivate;
 } // namespace Internal
 
-/* A highlighter for diffs. Parametrizable by the file indicator,
- *  which is for example '^====' in case of p4:
- * \code
-   ==== //depot/research/main/qdynamicmainwindow3/qdynamicdockwidgetlayout_p.h#34 (text) ====
- * \endcode
- * Or  '--- a/|'+++ b/' in case of git:
- * \code
-   diff --git a/src/plugins/plugins.pro b/src/plugins/plugins.pro
-   index 9401ee7..ef35c3b 100644
-   --- a/src/plugins/plugins.pro
-   +++ b/src/plugins/plugins.pro
-   @@ -10,6 +10,7 @@ SUBDIRS   = plugin_coreplugin \
- * \endcode
- * */
-
 class VCSBASE_EXPORT DiffHighlighter : public TextEditor::SyntaxHighlighter
 {
     Q_OBJECT

src/plugins/vcsbase/nicknamedialog.cpp

@@ -43,6 +43,18 @@
 
 enum { NickNameRole = Qt::UserRole + 1 };
 
+/*!
+    \class VCSBase::Internal::NickNameDialog
+
+    \brief Show users from mail cap file.
+
+    Manages a list of users read from an extended
+    mail cap file, consisting of 4 columns:  "Name Mail [AliasName [AliasMail]]".
+
+    The names can be used for insertion into "RevBy:" fields; aliases will
+    be preferred.
+*/
+
 namespace VCSBase {
 namespace Internal {
 

src/plugins/vcsbase/nicknamedialog.h

@@ -49,12 +49,6 @@ QT_END_NAMESPACE
 namespace VCSBase {
 namespace Internal {
 
-/* Nick name dialog: Manages a list of users read from an extended
- * mail cap file, consisting of 4 columns:
- * "Name Mail [AliasName [AliasMail]]".
- * The names can be used for insertion into "RevBy:" fields; aliases will
- * be preferred. */
-
 class NickNameDialog : public QDialog {
     Q_OBJECT
 public:

src/plugins/vcsbase/submiteditorfile.cpp

@@ -36,6 +36,12 @@
 using namespace VCSBase;
 using namespace VCSBase::Internal;
 
+/*!
+    \class VCSBase::Internal::SubmitEditorFile
+
+    \brief A non-saveable IFile for submit editor files.
+*/
+
 SubmitEditorFile::SubmitEditorFile(const QString &mimeType, QObject *parent) :
     Core::IFile(parent),
     m_mimeType(mimeType),

src/plugins/vcsbase/submiteditorfile.h

@@ -39,7 +39,6 @@
 namespace VCSBase {
 namespace Internal {
 
-// A non-saveable IFile for submit editor files.
 class SubmitEditorFile : public Core::IFile
 {
     Q_OBJECT

src/plugins/vcsbase/submitfilemodel.cpp

@@ -39,6 +39,13 @@
 
 namespace VCSBase {
 
+/*!
+    \class VCSBase::SubmitFileModel
+
+    \brief A 2-column (checkable, state, file name) model to be used to list the files
+    in the submit editor. Provides header items and a convience to add files.
+ */
+
 SubmitFileModel::SubmitFileModel(QObject *parent) :
     QStandardItemModel(0, 2, parent)
 {

src/plugins/vcsbase/submitfilemodel.h

@@ -40,9 +40,6 @@
 
 namespace VCSBase {
 
-/* A 2-column (checkable, state, file name) model to be used to list the files-
- * in the submit editor. Provides header items and a convience to add files. */
-
 class VCSBASE_EXPORT SubmitFileModel : public QStandardItemModel
 {
     Q_OBJECT

src/plugins/vcsbase/vcsbaseclient.cpp

@@ -56,6 +56,16 @@
 #include <QtCore/QByteArray>
 #include <QtCore/QMetaType>
 
+/*!
+    \class VCSBase::VCSBaseClient
+
+    \brief Base class for Mercurial and Bazaar 'clients'.
+
+    Provides base functionality for common commands (diff, log, etc).
+
+    \sa VCSBase::VCSJobRunner
+*/
+
 Q_DECLARE_METATYPE(QVariant)
 
 inline Core::IEditor *locateEditor(const Core::ICore *core, const char *property, const QString &entry)

src/plugins/vcsbase/vcsbaseclientsettings.cpp

@@ -39,6 +39,14 @@ using namespace VCSBase;
 
 enum { timeOutDefaultSeconds = 30 };
 
+/*!
+    \class VCSBase::VCSBaseClientSettings
+
+    \brief Settings used in VCSBaseClient.
+
+    \sa VCSBase::VCSBaseClient
+*/
+
 VCSBaseClientSettings::VCSBaseClientSettings() :
    m_binary(),
     m_logCount(0),

src/plugins/vcsbase/vcsbaseeditor.cpp

@@ -74,8 +74,34 @@
 #include <QtGui/QApplication>
 #include <QtGui/QMessageBox>
 
+/*!
+    \enum VCSBase::EditorContentType
+
+    \brief Contents of a VCSBaseEditor and its interaction.
+
+    \value RegularCommandOutput  No special handling.
+    \value LogOutput  Log of a file under revision control. Provide  'click on change'
+           description and 'Annotate' if is the log of a single file.
+    \value AnnotateOutput  Color contents per change number and provide 'click on change' description.
+           Context menu offers "Annotate previous version". Expected format:
+           \code
+           <change description>: file line
+           \endcode
+    \value DiffOutput  Diff output. Might includes describe output, which consists of a
+           header and diffs. Interaction is 'double click in  hunk' which
+           opens the file. Context menu offers 'Revert chunk'.
+
+    \sa VCSBase::VCSBaseEditorWidget
+*/
+
 namespace VCSBase {
 
+/*!
+    \class VCSBase::DiffChunk
+
+    \brief A diff chunk consisting of file name and chunk data.
+*/
+
 bool DiffChunk::isValid() const
 {
     return !fileName.isEmpty() && !chunk.isEmpty();
@@ -93,10 +119,16 @@ QByteArray DiffChunk::asPatch() const
     return rc;
 }
 
-// VCSBaseEditor: An editor with no support for duplicates.
+/*!
-// Creates a browse combo in the toolbar for diff output.
+    \class VCSBase::VCSBaseEditor
-// It also mirrors the signals of the VCSBaseEditor since the editor
+
-// manager passes the editor around.
+    \brief An editor with no support for duplicates.
+
+    Creates a browse combo in the toolbar for diff output.
+    It also mirrors the signals of the VCSBaseEditor since the editor
+    manager passes the editor around.
+*/
+
 class VCSBaseEditor : public TextEditor::BaseTextEditor
 {
     Q_OBJECT
@@ -197,7 +229,29 @@ VCSBaseEditorWidgetPrivate::VCSBaseEditorWidgetPrivate(const VCSBaseEditorParame
 {
 }
 
-// ------------ VCSBaseEditor
+/*!
+    \struct VCSBase::VCSBaseEditorParameters
+
+    \brief Helper struct used to parametrize an editor with mime type, context
+    and id. The extension is currently only a suggestion when running
+    VCS commands with redirection.
+
+    \sa VCSBase::VCSBaseEditorWidget, VCSBase::BaseVCSEditorFactory, VCSBase::EditorContentType
+*/
+
+/*!
+    \class VCSBase::VCSBaseEditorWidget
+
+    \brief Base class for editors showing version control system output
+    of the type enumerated by EditorContentType.
+
+    The source property should contain the file or directory the log
+    refers to and will be emitted with describeRequested().
+    This is for VCS that need a current directory.
+
+    \sa VCSBase::BaseVCSEditorFactory, VCSBase::VCSBaseEditorParameters, VCSBase::EditorContentType
+*/
+
 VCSBaseEditorWidget::VCSBaseEditorWidget(const VCSBaseEditorParameters *type, QWidget *parent)
   : BaseTextEditorWidget(parent),
     d(new VCSBaseEditorWidgetPrivate(type))

src/plugins/vcsbase/vcsbaseeditor.h

@@ -56,26 +56,14 @@ struct VCSBaseEditorWidgetPrivate;
 class DiffHighlighter;
 class BaseAnnotationHighlighter;
 
-// Contents of a VCSBaseEditor and its interaction.
+// Documentation inside
 enum EditorContentType {
-    // No special handling.
     RegularCommandOutput,
-    // Log of a file under revision control. Provide  'click on change'
-    // description and 'Annotate' if is the log of a single file.
     LogOutput,
-    // <change description>: file line
-    // Color per change number and provide 'click on change' description.
-    // Context menu offers "Annotate previous version".
     AnnotateOutput,
-    // Diff output. Might includes describe output, which consists of a
-    // header and diffs. Interaction is 'double click in  hunk' which
-    // opens the file
     DiffOutput
 };
 
-// Helper struct used to parametrize an editor with mime type, context
-// and id. The extension is currently only a suggestion when running
-// VCS commands with redirection.
 struct VCSBASE_EXPORT VCSBaseEditorParameters
 {
     EditorContentType type;
@@ -96,11 +84,6 @@ public:
     QByteArray chunk;
 };
 
-// Base class for editors showing version control system output
-// of the type enumerated by EditorContentType.
-// The source property should contain the file or directory the log
-// refers to and will be emitted with describeRequested().
-// This is for VCS that need a current directory.
 class VCSBASE_EXPORT VCSBaseEditorWidget : public TextEditor::BaseTextEditorWidget
 {
     Q_PROPERTY(QString source READ source WRITE setSource)

src/plugins/vcsbase/vcsbaseoptionspage.cpp

@@ -38,6 +38,12 @@
 #include <QtCore/QCoreApplication>
 #include <QtGui/QIcon>
 
+/*!
+    \class VCSBase::VCSBaseOptionsPage
+
+    \brief Base class for VCS options pages providing common category/icon.
+ */
+
 namespace VCSBase {
 
 VCSBaseOptionsPage::VCSBaseOptionsPage(QObject *parent) :

src/plugins/vcsbase/vcsbaseoptionspage.h

@@ -40,9 +40,6 @@
 
 namespace VCSBase {
 
-/**
- * An abstract options page in the Version Control category.
- */
 class VCSBASE_EXPORT VCSBaseOptionsPage : public Core::IOptionsPage
 {
     Q_OBJECT

src/plugins/vcsbase/vcsbaseoutputwindow.cpp

@@ -53,6 +53,21 @@
 #include <QtCore/QPoint>
 #include <QtCore/QFileInfo>
 
+/*!
+    \class VCSBase::VCSBaseOutputWindow
+
+    \brief Output window for Version Control System command and other output (Singleton).
+
+    Installed by the base plugin and accessible for the other plugins
+    via static instance()-accessor. Provides slots to append output with
+    special formatting.
+
+    It is possible to associate a repository with plain log text, enabling
+    an "Open" context menu action over relative file name tokens in the text
+    (absolute paths will also work). This can be used for "status" logs,
+    showing modified file names, allowing the user to open them.
+*/
+
 namespace VCSBase {
 
 namespace Internal {

src/plugins/vcsbase/vcsbaseoutputwindow.h

@@ -42,15 +42,6 @@ namespace VCSBase {
 
 struct VCSBaseOutputWindowPrivate;
 
-/* Common OutputWindow for Version Control System command and other output.
- * Installed by the base plugin and accessible for the other plugins
- * via static instance()-accessor. Provides slots to append output with
- * special formatting.
- * It is possible to associate a repository with plain log text, enabling
- * an "Open" context menu action over relative file name tokens in the text
- * (absolute paths will also work). This can be used for "status" logs,
- * showing modified file names, allowing the user to open them. */
-
 class VCSBASE_EXPORT VCSBaseOutputWindow : public Core::IOutputPane
 {
     Q_OBJECT

src/plugins/vcsbase/vcsbaseplugin.cpp

@@ -67,12 +67,27 @@
 
 enum { debug = 0, debugRepositorySearch = 0, debugExecution = 0 };
 
-namespace VCSBase {
+/*!
+    \namespace VCSBase
+    VCSBase plugin namespace
+*/
 
+/*!
+    \namespace VCSBase::Internal
+    Internal namespace of the VCSBase plugin
+    \internal
+*/
+
+namespace VCSBase {
 namespace Internal {
 
-// Internal state created by the state listener and
+/*!
-// VCSBasePluginState.
+    \struct VCSBase::Internal::State
+
+    \brief Internal state created by the state listener and VCSBasePluginState.
+
+    Aggregated in the QSharedData of VCSBase::VCSBasePluginState.
+*/
 
 struct State {
     void clearFile();
@@ -166,8 +181,14 @@ QDebug operator<<(QDebug in, const State &state)
     return in;
 }
 
-// StateListener: Connects to the relevant signals, tries to find version
+/*!
-// controls and emits signals to the plugin instances.
+    \class VCSBase::Internal::StateListener
+
+    \brief Connects to the relevant signals of Qt Creator, tries to find version
+    controls and emits signals to the plugin instances.
+
+    Singleton (as not to do checks multiple times).
+*/
 
 class StateListener : public QObject {
     Q_OBJECT
@@ -281,6 +302,21 @@ public:
     Internal::State m_state;
 };
 
+/*!
+    \class  VCSBase::VCSBasePluginState
+
+    \brief Relevant state information of the VCS plugins
+
+    Qt Creator's state relevant to VCS plugins is a tuple of
+
+    \list
+    \o Current file and it's version system control/top level
+    \o Current project and it's version system control/top level
+    \endlist
+
+    \sa VCSBase::VCSBasePlugin
+*/
+
 VCSBasePluginState::VCSBasePluginState() : data(new VCSBasePluginStateData)
 {
 }
@@ -416,7 +452,34 @@ VCSBASE_EXPORT QDebug operator<<(QDebug in, const VCSBasePluginState &state)
     return in;
 }
 
-//  VCSBasePlugin
+/*!
+    \class VCSBase::VCSBasePlugin
+
+    \brief Base class for all version control plugins.
+
+    The plugin connects to the
+    relevant change signals in Qt Creator and calls the virtual
+    updateActions() for the plugins to update their menu actions
+    according to the new state. This is done centrally to avoid
+    single plugins repeatedly invoking searches/QFileInfo on files,
+    etc.
+
+    Independently, there are accessors for current patch files, which return
+    a file name if the current file could be a patch file which could be applied
+    and a repository exists.
+
+    If current file/project are managed
+    by different version controls, the project is discarded and only
+    the current file is taken into account, allowing to do a diff
+    also when the project of a file is not opened.
+
+    When triggering an action, a copy of the state should be made to
+    keep it, as it may rapidly change due to context changes, etc.
+
+    The class also detects the VCS plugin submit editor closing and calls
+    the virtual submitEditorAboutToClose() to trigger the submit process.
+*/
+
 struct VCSBasePluginPrivate {
     explicit VCSBasePluginPrivate(const QString &submitEditorId);
 

src/plugins/vcsbase/vcsbaseplugin.h

@@ -65,34 +65,7 @@ struct VCSBasePluginPrivate;
 class VCSBasePluginStateData;
 class VCSBasePlugin;
 
-/* VCSBasePlugin and VCSBasePluginState: Provide a base class for
+// Documentation inside.
- * VCS plugins. It mainly takes care of maintaining the
- * VCS-relevant state of Qt Creator which is a tuple of
- *
- * 1) Current file    and it's version system control/top level
- * 2) Current project and it's version system control/top level
- *
- * (reflected in VCSBasePluginState). The plugin connects to the
- * relevant change signals in Qt Creator and calls the virtual
- * updateActions() for the plugins to update their menu actions
- * according to the new state. This is done centrally to avoid
- * single plugins repeatedly invoking searches/QFileInfo on files,
- * etc.
- * Independently, there are accessors for current patch files, which return
- * a file name if the current file could be a patch file which could be applied
- * and a repository exists.
- *
- * If current file/project are managed
- * by different version controls, the project is discarded and only
- * the current file is taken into account, allowing to do a diff
- * also when the project of a file is not opened.
- *
- * When triggering an action, a copy of the state should be made to
- * keep it, as it may rapidly change due to context changes, etc.
- *
- * The class also detects the VCS plugin submit editor closing and calls
- * the virtual submitEditorAboutToClose() to trigger the submit process. */
-
 class VCSBASE_EXPORT VCSBasePluginState
 {
 public:

src/plugins/vcsbase/vcsbasesubmiteditor.cpp

@@ -78,6 +78,40 @@
 enum { debug = 0 };
 enum { wantToolBar = 0 };
 
+/*!
+    \struct VCSBase::VCSBaseSubmitEditorParameters
+
+    \brief Utility struct to parametrize a VCSBaseSubmitEditor.
+*/
+
+/*!
+    \class  VCSBase::VCSBaseSubmitEditor
+
+    \brief Base class for a submit editor based on the Utils::SubmitEditorWidget.
+
+    Presents the commit message in a text editor and an
+    checkable list of modified files in a list window. The user can delete
+    files from the list by pressing unchecking them or diff the selection
+    by doubleclicking.
+
+    The action matching the the ids (unless 0) of the parameter struct will be
+    registered with the EditorWidget and submit/diff actions will be added to
+    a toolbar.
+
+    For the given context, there must be only one instance of the editor
+    active.
+    To start a submit, set the submit template on the editor and the output
+    of the VCS status command listing the modified files as fileList and open
+    it.
+
+    The submit process is started by listening on the editor close
+    signal and then asking the IFile interface of the editor to save the file
+    within a IFileManager::blockFileChange() section
+    and to launch the submit process. In addition, the action registered
+    for submit should be connected to a slot triggering the close of the
+    current editor in the editor manager.
+*/
+
 namespace VCSBase {
 
 static inline QString submitMessageCheckScript()

src/plugins/vcsbase/vcsbasesubmiteditor.h

@@ -56,7 +56,6 @@ namespace Internal {
 }
 struct VCSBaseSubmitEditorPrivate;
 
-/* Utility struct to parametrize a VCSBaseSubmitEditor. */
 struct VCSBASE_EXPORT VCSBaseSubmitEditorParameters {
     const char *mimeType;
     const char *id;
@@ -64,28 +63,6 @@ struct VCSBASE_EXPORT VCSBaseSubmitEditorParameters {
     const char *context;
 };
 
-/* Base class for a submit editor based on the Utils::SubmitEditorWidget
- * that presents the commit message in a text editor and an
- * checkable list of modified files in a list window. The user can delete
- * files from the list by pressing unchecking them or diff the selection
- * by doubleclicking.
- *
- * The action matching the the ids (unless 0) of the parameter struct will be
- * registered with the EditorWidget and submit/diff actions will be added to
- * a toolbar.
- *
- * For the given context, there must be only one instance of the editor
- * active.
- * To start a submit, set the submit template on the editor and the output
- * of the VCS status command listing the modified files as fileList and open
- * it.
- * The submit process is started by listening on the editor close
- * signal and then asking the IFile interface of the editor to save the file
- * within a IFileManager::blockFileChange() section
- * and to launch the submit process. In addition, the action registered
- * for submit should be connected to a slot triggering the close of the
- * current editor in the editor manager. */
-
 class VCSBASE_EXPORT VCSBaseSubmitEditor : public Core::IEditor
 {
     Q_OBJECT

src/plugins/vcsbase/vcsjobrunner.cpp

@@ -50,6 +50,16 @@
 #include <QtCore/QWaitCondition>
 #include <QtCore/QSharedPointer>
 
+/*!
+    \class  VCSBase::VCSJob
+
+    \brief Version control system background command execution job.
+
+    Takes arguments, etc. as parameters and emits signals on output/termination.
+
+    \sa VCSBase::VCSJobRunner, VCSBase::VCSBaseClient
+*/
+
 namespace VCSBase {
 
 VCSJob::VCSJob(const QString &workingDir,
@@ -128,6 +138,17 @@ void VCSJob::setUnixTerminalDisabled(bool v)
     m_unixTerminalDisabled = v;
 }
 
+/*!
+    \class  VCSBase::VCSJobRunner
+
+    \brief Job queue for version control system background command execution.
+
+    A job queue running in a separate thread, executing commands
+    and emitting status/log  signals.
+
+    \sa VCSBase::VCSJob, VCSBase::VCSBaseClient
+*/
+
 class VCSJobRunnerPrivate
 {
 public:

src/plugins/vcsbase/vcsjobrunner.h

@@ -95,8 +95,6 @@ private:
     bool m_unixTerminalDisabled;
 };
 
-/* A job queue running in a separate thread, executing commands
- * and emitting status/log  signals. */
 class VCSBASE_EXPORT VCSJobRunner : public QThread
 {
     Q_OBJECT