API Documentation: Add VCSBase.

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);