Commit 58111b2d authored by Friedemann Kleint's avatar Friedemann Kleint

API Documentation: Add VCSBase.

parent 34a96d88
......@@ -108,6 +108,10 @@
\o \l{Debugger}
\o Debugging functionality.
\row
\o \l{VCSBase}
\o Base classes for version control support.
\endtable
*/
......
......@@ -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.
......
......@@ -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 {
......
......@@ -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
......
......@@ -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 {
......
......@@ -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
......
......@@ -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 {
......
......@@ -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)
......
......@@ -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
......
......@@ -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
......
......@@ -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())
{
......
......@@ -70,8 +70,6 @@ signals:
void output(const QString &what);
};
/* Convenience implementation using a QProcess. */
class VCSBASE_EXPORT ProcessCheckoutJob : public AbstractCheckoutJob
{
Q_OBJECT
......
......@@ -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 {
......
......@@ -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)
......
......@@ -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 {
......
......@@ -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:
......
......@@ -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 };
......
......@@ -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:
......
......@@ -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 {
......
......@@ -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
......@@ -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;
......
......@@ -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
......
......@@ -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 {
......
......@@ -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:
......
......@@ -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),
......
......@@ -39,7 +39,6 @@
namespace VCSBase {
namespace Internal {
// A non-saveable IFile for submit editor files.
class SubmitEditorFile : public Core::IFile
{
Q_OBJECT
......
......@@ -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)
{
......
......@@ -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
......
......@@ -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)
......
......@@ -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),
......
......@@ -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.
// It also mirrors the signals of the VCSBaseEditor since the editor
// manager passes the editor around.
/*!
\class VCSBase::VCSBaseEditor
\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))
......
......@@ -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)
......
......@@ -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) :
......
......@@ -40,9 +40,6 @@
namespace VCSBase {
/**
* An abstract options page in the Version Control category.
*/
class VCSBASE_EXPORT VCSBaseOptionsPage : public Core::IOptionsPage
{
Q_OBJECT
......
......@@ -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 {
......
......@@ -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