diff options
Diffstat (limited to 'src/plugins/projectexplorer')
54 files changed, 970 insertions, 437 deletions
diff --git a/src/plugins/projectexplorer/abi.cpp b/src/plugins/projectexplorer/abi.cpp index 50e89ba452..57b22784a4 100644 --- a/src/plugins/projectexplorer/abi.cpp +++ b/src/plugins/projectexplorer/abi.cpp @@ -39,6 +39,14 @@ #include <QtCore/QStringList> #include <QtCore/QSysInfo> +/*! + \class ProjectExplorer::Abi + + \brief Represents the Application Binary Interface (ABI) of a target platform. + + \sa ProjectExplorer::ToolChain +*/ + namespace ProjectExplorer { // -------------------------------------------------------------------------- @@ -258,6 +266,7 @@ Abi::Abi(const QString &abiString) : else if (abiParts.at(1) == QLatin1String("windows")) m_os = WindowsOS; else + return; } diff --git a/src/plugins/projectexplorer/abi.h b/src/plugins/projectexplorer/abi.h index 66a749873e..2d7196c73d 100644 --- a/src/plugins/projectexplorer/abi.h +++ b/src/plugins/projectexplorer/abi.h @@ -40,7 +40,7 @@ namespace ProjectExplorer { // -------------------------------------------------------------------------- -// ABI +// ABI (documentation inside) // -------------------------------------------------------------------------- class PROJECTEXPLORER_EXPORT Abi diff --git a/src/plugins/projectexplorer/abstractprocessstep.cpp b/src/plugins/projectexplorer/abstractprocessstep.cpp index aeb4eb0221..2b0dce58de 100644 --- a/src/plugins/projectexplorer/abstractprocessstep.cpp +++ b/src/plugins/projectexplorer/abstractprocessstep.cpp @@ -46,6 +46,49 @@ using namespace ProjectExplorer; +/*! + \class ProjectExplorer::AbstractProcessStep + + \brief A convenience class, which can be used as a base class instead of BuildStep. + + It should be used as a base class if your buildstep just needs to run a process. + + Usage: + \list + \o Use processParameters() to configure the process you want to run + (you need to do that before calling AbstractProcessStep::init()). + \o Inside YourBuildStep::init() call AbstractProcessStep::init(). + \o Inside YourBuildStep::run() call AbstractProcessStep::run(), which automatically starts the proces + and by default adds the output on stdOut and stdErr to the OutputWindow. + \o If you need to process the process output override stdOut() and/or stdErr. + \endlist + + The two functions processStarted() and processFinished() are called after starting/finishing the process. + By default they add a message to the output window. + + Use setEnabled() to control whether the BuildStep needs to run. (A disabled BuildStep immediately returns true, + from the run function.) + + \sa ProjectExplorer::ProcessParameters +*/ + +/*! + \fn void ProjectExplorer::AbstractProcessStep::setEnabled(bool b) + + \brief Enables or disables a BuildStep. + + Disabled BuildSteps immediately return true from their run method. + Should be called from init() +*/ + +/*! + \fn ProcessParameters *ProjectExplorer::AbstractProcessStep::processParameters() + + \brief Obtain a reference to the parameters for the actual process to run. + + Should be used in init() +*/ + AbstractProcessStep::AbstractProcessStep(BuildStepList *bsl, const QString &id) : BuildStep(bsl, id), m_timer(0), m_futureInterface(0), m_enabled(true), m_ignoreReturnValue(false), @@ -69,6 +112,13 @@ AbstractProcessStep::~AbstractProcessStep() delete m_outputParserChain; } +/*! + \brief Delete all existing output parsers and start a new chain with the + given parser. + + Derived classes need to call this function. +*/ + void AbstractProcessStep::setOutputParser(ProjectExplorer::IOutputParser *parser) { delete m_outputParserChain; @@ -82,6 +132,10 @@ void AbstractProcessStep::setOutputParser(ProjectExplorer::IOutputParser *parser } } +/*! + \brief Append the given output parser to the existing chain of parsers. +*/ + void AbstractProcessStep::appendOutputParser(ProjectExplorer::IOutputParser *parser) { if (!parser) @@ -97,16 +151,32 @@ ProjectExplorer::IOutputParser *AbstractProcessStep::outputParser() const return m_outputParserChain; } +/*! + \brief If ignoreReturnValue is set to true, then the abstractprocess step will + return success even if the return value indicates otherwise. + + Should be called from init. +*/ + void AbstractProcessStep::setIgnoreReturnValue(bool b) { m_ignoreReturnValue = b; } +/*! + \brief Reimplemented from BuildStep::init(). You need to call this from + YourBuildStep::init() +*/ + bool AbstractProcessStep::init() { return true; } +/*! + \brief Reimplemented from BuildStep::init(). You need to call this from YourBuildStep::run() +*/ + void AbstractProcessStep::run(QFutureInterface<bool> &fi) { m_futureInterface = &fi; @@ -172,6 +242,12 @@ void AbstractProcessStep::run(QFutureInterface<bool> &fi) return; } +/*! + \brief Called after the process is started. + + The default implementation adds a process started message to the output message +*/ + void AbstractProcessStep::processStarted() { emit addOutput(tr("Starting: \"%1\" %2") @@ -180,6 +256,12 @@ void AbstractProcessStep::processStarted() BuildStep::MessageOutput); } +/*! + \brief Called after the process Finished. + + The default implementation adds a line to the output window +*/ + void AbstractProcessStep::processFinished(int exitCode, QProcess::ExitStatus status) { QString command = QDir::toNativeSeparators(m_param.effectiveCommand()); @@ -195,6 +277,12 @@ void AbstractProcessStep::processFinished(int exitCode, QProcess::ExitStatus sta } } +/*! + \brief Called if the process could not be started. + + By default adds a message to the output window. +*/ + void AbstractProcessStep::processStartupFailed() { emit addOutput(tr("Could not start process \"%1\" %2") @@ -203,6 +291,10 @@ void AbstractProcessStep::processStartupFailed() BuildStep::ErrorMessageOutput); } +/*! + \brief Called to test whether a prcess succeeded or not. +*/ + bool AbstractProcessStep::processSucceeded(int exitCode, QProcess::ExitStatus status) { return exitCode == 0 && status == QProcess::NormalExit; @@ -217,6 +309,12 @@ void AbstractProcessStep::processReadyReadStdOutput() } } +/*! + \brief Called for each line of output on stdOut(). + + The default implementation adds the line to the application output window. +*/ + void AbstractProcessStep::stdOutput(const QString &line) { if (m_outputParserChain) @@ -233,6 +331,12 @@ void AbstractProcessStep::processReadyReadStdError() } } +/*! + \brief Called for each line of output on StdErrror(). + + The default implementation adds the line to the application output window +*/ + void AbstractProcessStep::stdError(const QString &line) { if (m_outputParserChain) diff --git a/src/plugins/projectexplorer/abstractprocessstep.h b/src/plugins/projectexplorer/abstractprocessstep.h index 69f0c36dd0..bea9716e35 100644 --- a/src/plugins/projectexplorer/abstractprocessstep.h +++ b/src/plugins/projectexplorer/abstractprocessstep.h @@ -50,26 +50,7 @@ QT_END_NAMESPACE namespace ProjectExplorer { class IOutputParser; - -/*! - AbstractProcessStep is a convenience class, which can be used as a base class instead of BuildStep. - It should be used as a base class if your buildstep just needs to run a process. - - Usage: - Use processParameters() to configure the process you want to run - (you need to do that before calling AbstractProcessStep::init()). - Inside YourBuildStep::init() call AbstractProcessStep::init(). - Inside YourBuildStep::run() call AbstractProcessStep::run(), which automatically starts the proces - and by default adds the output on stdOut and stdErr to the OutputWindow. - If you need to process the process output override stdOut() and/or stdErr. - The two functions processStarted() and processFinished() are called after starting/finishing the process. - By default they add a message to the output window. - - Use setEnabled() to control whether the BuildStep needs to run. (A disabled BuildStep immediately returns true, - from the run function.) - -*/ - +// Documentation inside. class PROJECTEXPLORER_EXPORT AbstractProcessStep : public BuildStep { Q_OBJECT @@ -77,35 +58,19 @@ class PROJECTEXPLORER_EXPORT AbstractProcessStep : public BuildStep public: virtual ~AbstractProcessStep(); - /// reimplemented from BuildStep::init() - /// You need to call this from YourBuildStep::init() virtual bool init(); - /// reimplemented from BuildStep::init() - /// You need to call this from YourBuildStep::run() virtual void run(QFutureInterface<bool> &); virtual BuildStepConfigWidget *createConfigWidget() = 0; virtual bool immutable() const = 0; - /// enables or disables a BuildStep - /// Disabled BuildSteps immediately return true from their run method - /// should be called from init() void setEnabled(bool b) { m_enabled = b; } - /// obtain a reference to the parameters for the actual process to run. - /// should be used in init() ProcessParameters *processParameters() { return &m_param; } - /// If ignoreReturnValue is set to true, then the abstractprocess step will - /// return success even if the return value indicates otherwise - /// should be called from init void setIgnoreReturnValue(bool b); - // derived classes needs to call this function - /// Delete all existing output parsers and start a new chain with the - /// given parser. void setOutputParser(ProjectExplorer::IOutputParser *parser); - /// Append the given output parser to the existing chain of parsers. void appendOutputParser(ProjectExplorer::IOutputParser *parser); ProjectExplorer::IOutputParser *outputParser() const; @@ -113,24 +78,11 @@ protected: AbstractProcessStep(BuildStepList *bsl, const QString &id); AbstractProcessStep(BuildStepList *bsl, AbstractProcessStep *bs); - /// Called after the process is started - /// the default implementation adds a process started message to the output message virtual void processStarted(); - /// Called after the process Finished - /// the default implementation adds a line to the output window virtual void processFinished(int exitCode, QProcess::ExitStatus status); - /// Called if the process could not be started, - /// by default adds a message to the output window virtual void processStartupFailed(); - /// Called to test whether a prcess succeeded or not. virtual bool processSucceeded(int exitCode, QProcess::ExitStatus status); - /// Called for each line of output on stdOut() - /// the default implementation adds the line to the - /// application output window virtual void stdOutput(const QString &line); - /// Called for each line of output on StdErrror() - /// the default implementation adds the line to the - /// application output window virtual void stdError(const QString &line); private slots: diff --git a/src/plugins/projectexplorer/applicationlauncher.h b/src/plugins/projectexplorer/applicationlauncher.h index e463750d66..438285fba7 100644 --- a/src/plugins/projectexplorer/applicationlauncher.h +++ b/src/plugins/projectexplorer/applicationlauncher.h @@ -45,6 +45,7 @@ class Environment; namespace ProjectExplorer { struct ApplicationLauncherPrivate; +// Documentation inside. class PROJECTEXPLORER_EXPORT ApplicationLauncher : public QObject { Q_OBJECT diff --git a/src/plugins/projectexplorer/applicationlauncher_x11.cpp b/src/plugins/projectexplorer/applicationlauncher_x11.cpp index 5a736c8def..783206f9c4 100644 --- a/src/plugins/projectexplorer/applicationlauncher_x11.cpp +++ b/src/plugins/projectexplorer/applicationlauncher_x11.cpp @@ -40,6 +40,17 @@ #include <QtCore/QTimer> #include <QtCore/QTextCodec> +/*! + \class ProjectExplorer::ApplicationLauncher + + \brief Application launcher of the ProjectExplorer plugin. + + Encapsulates processes running in a console or as GUI processes, + captures debug output of GUI processes on Windows (outputDebugString()). + + \sa Utils::ConsoleProcess +*/ + namespace ProjectExplorer { struct ApplicationLauncherPrivate { diff --git a/src/plugins/projectexplorer/baseprojectwizarddialog.cpp b/src/plugins/projectexplorer/baseprojectwizarddialog.cpp index b6348767ff..a936d84aa5 100644 --- a/src/plugins/projectexplorer/baseprojectwizarddialog.cpp +++ b/src/plugins/projectexplorer/baseprojectwizarddialog.cpp @@ -39,6 +39,15 @@ #include <QtCore/QDir> +/*! + \class ProjectExplorer::BaseProjectWizardDialog + + \brief Base class for project wizards. + + Presents the introductory page and takes care of setting the folder choosen + as default projects' folder should the user wish to do that. +*/ + namespace ProjectExplorer { struct BaseProjectWizardDialogPrivate { diff --git a/src/plugins/projectexplorer/baseprojectwizarddialog.h b/src/plugins/projectexplorer/baseprojectwizarddialog.h index 07f3182f53..816249202f 100644 --- a/src/plugins/projectexplorer/baseprojectwizarddialog.h +++ b/src/plugins/projectexplorer/baseprojectwizarddialog.h @@ -46,10 +46,7 @@ namespace ProjectExplorer { struct BaseProjectWizardDialogPrivate; -/* BaseProjectWizardDialog: Presents the introductory - * page and takes care of setting the directory as default - * should the user wish to do that. */ - +// Documentation inside. class PROJECTEXPLORER_EXPORT BaseProjectWizardDialog : public Utils::Wizard { Q_OBJECT diff --git a/src/plugins/projectexplorer/buildconfigurationmodel.cpp b/src/plugins/projectexplorer/buildconfigurationmodel.cpp index 4208f152c1..21029da3d6 100644 --- a/src/plugins/projectexplorer/buildconfigurationmodel.cpp +++ b/src/plugins/projectexplorer/buildconfigurationmodel.cpp @@ -36,9 +36,15 @@ using namespace ProjectExplorer; -/// -/// RunConfigurationsModel -/// +/*! + \class ProjectExplorer::BuildConfigurationModel + \brief A model to represent the build configurations of a target. + + To be used in for the drop down of comboboxes. + Does automatically adjust itself to added and removed BuildConfigurations + Very similar to the Run Configuration Model. + TODO might it possible to share code without making the code a complete mess. +*/ class BuildConfigurationComparer { diff --git a/src/plugins/projectexplorer/buildconfigurationmodel.h b/src/plugins/projectexplorer/buildconfigurationmodel.h index c2215bac47..6df8222820 100644 --- a/src/plugins/projectexplorer/buildconfigurationmodel.h +++ b/src/plugins/projectexplorer/buildconfigurationmodel.h @@ -39,12 +39,7 @@ namespace ProjectExplorer { class Target; class BuildConfiguration; -/*! A model to represent the build configurations of a target. - To be used in for the drop down of comboboxes - Does automatically adjust itself to added and removed BuildConfigurations - Very similar to the Run Configuration Model - TOOD might it possible to share code without making the code a complete mess -*/ +// Documentation inside. class BuildConfigurationModel : public QAbstractListModel { Q_OBJECT diff --git a/src/plugins/projectexplorer/buildstep.cpp b/src/plugins/projectexplorer/buildstep.cpp index 4f0699ad23..7eff11522d 100644 --- a/src/plugins/projectexplorer/buildstep.cpp +++ b/src/plugins/projectexplorer/buildstep.cpp @@ -37,6 +37,75 @@ #include "deployconfiguration.h" #include "target.h" +/*! + \class ProjectExplorer::BuildStep + + \brief BuildSteps are the primary way plugin developers can customize + how their projects (or projects from other plugins) are build. + + Building a project, is done by taking the list of buildsteps + from the project and calling first init() than run() on them. + + That means to change the way your project is build, reimplemnt + this class and add your Step to the buildStep list of the project. + + Note: The projects own the buildstep, do not delete them yourself. + + init() is called in the GUI thread and can be used to query the + project for any information you need. + + run() is run via QtConccurrent in a own thread, if you need an + eventloop you need to create it yourself! +*/ + +/*! + \fn bool ProjectExplorer::BuildStep::init() + + This function is run in the gui thread, + use it to retrieve any information that you need in run() +*/ + +/*! + \fn void ProjectExplorer::BuildStep::run(QFutureInterface<bool> &fi) + + Reimplement this. This function is called when the target is build. + This function is NOT run in the gui thread. It runs in its own thread + If you need an event loop, you need to create one. + + The absolute minimal implementation is: + \code + fi.reportResult(true); + \endcode +*/ + +/*! + \fn BuildStepConfigWidget *ProjectExplorer::BuildStep::createConfigWidget() + + Returns the Widget shown in the target settings dialog for this buildStep; + ownership is transferred to the caller. +*/ + +/*! + \fn bool ProjectExplorer::BuildStep::immutable() const + + If this function returns true, the user can't delete this BuildStep for this target + and the user is prevented from changing the order immutable steps are run + the default implementation returns false. +*/ + +/*! + \fn void ProjectExplorer::BuildStep::addTask(const ProjectExplorer::Task &task) + \brief Add a task. +*/ + +/*! + \fn void addOutput(const QString &string, ProjectExplorer::BuildStep::OutputFormat format, + ProjectExplorer::BuildStep::OutputNewlineSetting newlineSetting) + + The string is added to the generated output, usually in the output window. + It should be in plain text, with the format in the parameter. +*/ + using namespace ProjectExplorer; BuildStep::BuildStep(BuildStepList *bsl, const QString &id) : diff --git a/src/plugins/projectexplorer/buildstep.h b/src/plugins/projectexplorer/buildstep.h index d10439adfb..c8c88a110a 100644 --- a/src/plugins/projectexplorer/buildstep.h +++ b/src/plugins/projectexplorer/buildstep.h @@ -47,28 +47,9 @@ class BuildStepList; class DeployConfiguration; class Target; -/* -// BuildSteps are the primary way plugin developers can customize -// how their projects (or projects from other plugins) are build. -// -// Building a project, is done by taking the list of buildsteps -// from the project and calling first init() than run() on them. -// -// That means to change the way your project is build, reimplemnt -// this class and add your Step to the buildStep list of the project. -// -// Note: The projects own the buildstep, do not delete them yourself. -// -// init() is called in the GUI thread and can be used to query the -// project for any information you need. -// -// run() is run via QtConccurrent in a own thread, if you need an -// eventloop you need to create it yourself! -// -*/ - class BuildStepConfigWidget; +// Documentation inside. class PROJECTEXPLORER_EXPORT BuildStep : public ProjectConfiguration { Q_OBJECT @@ -80,24 +61,12 @@ protected: public: virtual ~BuildStep(); - // This function is run in the gui thread, - // use it to retrieve any information that you need in run() virtual bool init() = 0; - // Reimplement this. This function is called when the target is build. - // This function is NOT run in the gui thread. It runs in its own thread - // If you need an event loop, you need to create one. - // The absolute minimal implementation is: - // fi.reportResult(true); virtual void run(QFutureInterface<bool> &fi) = 0; - // the Widget shown in the target settings dialog for this buildStep - // ownership is transferred to the caller virtual BuildStepConfigWidget *createConfigWidget() = 0; - // if this function returns true, the user can't delete this BuildStep for this target - // and the user is prevented from changing the order immutable steps are run - // the default implementation returns false virtual bool immutable() const; BuildConfiguration *buildConfiguration() const; @@ -108,12 +77,8 @@ public: enum OutputNewlineSetting { DoAppendNewline, DontAppendNewline }; signals: - // Add a task. void addTask(const ProjectExplorer::Task &task); - // The string is added to the generated output, usually in the output - // window. - // It should be in plain text, with the format in the parameter void addOutput(const QString &string, ProjectExplorer::BuildStep::OutputFormat format, ProjectExplorer::BuildStep::OutputNewlineSetting newlineSetting = DoAppendNewline); }; diff --git a/src/plugins/projectexplorer/customwizard/customwizard.cpp b/src/plugins/projectexplorer/customwizard/customwizard.cpp index 492a5bdf19..a9e0dde744 100644 --- a/src/plugins/projectexplorer/customwizard/customwizard.cpp +++ b/src/plugins/projectexplorer/customwizard/customwizard.cpp @@ -55,6 +55,20 @@ static const char configFileC[] = "wizard.xml"; namespace ProjectExplorer { +/*! + \class ProjectExplorer::ICustomWizardFactory + \brief Factory for creating custom wizards extending the base class + (CustomWizard or CustomProjectWizard) + + The factory can be registered under a name in CustomWizard. The name can + be specified in the \c <wizard class=''...> attribute in the \c wizard.xml file + and thus allows for specifying a C++ derived wizard class. + For example, this is currently used in Qt4ProjectManager to get Qt-specific + aspects into the custom wizard. + + \sa ProjectExplorer::CustomWizard, ProjectExplorer::CustomProjectWizard +*/ + struct CustomWizardPrivate { CustomWizardPrivate() : m_context(new Internal::CustomWizardContext) {} @@ -65,6 +79,16 @@ struct CustomWizardPrivate { int CustomWizardPrivate::verbose = 0; +/*! + \class ProjectExplorer::CustomWizard + + \brief Base classes for custom wizards based on file templates and a XML + configuration file (\c share/qtcreator/templates/wizards). + + Presents CustomWizardDialog (fields page containing path control) for wizards + of type "class" or "file". Serves as base class for project wizards. +*/ + CustomWizard::CustomWizard(const Core::BaseFileWizardParameters& baseFileParameters, QObject *parent) : Core::BaseFileWizard(baseFileParameters, parent), @@ -379,8 +403,16 @@ static QString listWizards() return rc; } -// Scan the subdirectories of the template directory for directories -// containing valid configuration files and parse them into wizards. +/*! + \brief Reads \c share/qtcreator/templates/wizards and creates all custom wizards. + + As other plugins might register factories for derived + classes, call it in extensionsInitialized(). + + Scans the subdirectories of the template directory for directories + containing valid configuration files and parse them into wizards. +*/ + QList<CustomWizard*> CustomWizard::createWizards() { QList<CustomWizard*> rc; @@ -464,7 +496,17 @@ QList<CustomWizard*> CustomWizard::createWizards() return rc; } -// --------------- CustomProjectWizard +/*! + \class ProjectExplorer::CustomProjectWizard + \brief A custom project wizard. + + Presents a CustomProjectWizardDialog (Project intro page and fields page) + for wizards of type "project". + Overwrites postGenerateFiles() to open the project files according to the + file attributes. Also inserts \c '%ProjectName%' into the base + replacement map once the intro page is left to have it available + for QLineEdit-type fields' default text. +*/ CustomProjectWizard::CustomProjectWizard(const Core::BaseFileWizardParameters& baseFileParameters, QObject *parent) : @@ -472,6 +514,12 @@ CustomProjectWizard::CustomProjectWizard(const Core::BaseFileWizardParameters& b { } +/*! + \brief Can be reimplemented to create custom project wizards. + + initProjectWizardDialog() needs to be called. +*/ + QWizard *CustomProjectWizard::createWizardDialog(QWidget *parent, const QString &defaultPath, const WizardPageList &extensionPages) const @@ -529,6 +577,11 @@ Core::GeneratedFiles CustomProjectWizard::generateFiles(const QWizard *w, QStrin return generatedFiles; } +/*! + \brief Utility to open the projects and editors for the files that have + the respective attributes set. +*/ + bool CustomProjectWizard::postGenerateOpen(const Core::GeneratedFiles &l, QString *errorMessage) { // Post-Generate: Open the project and the editors as desired diff --git a/src/plugins/projectexplorer/customwizard/customwizard.h b/src/plugins/projectexplorer/customwizard/customwizard.h index 0b0f923fbb..815a703b59 100644 --- a/src/plugins/projectexplorer/customwizard/customwizard.h +++ b/src/plugins/projectexplorer/customwizard/customwizard.h @@ -59,11 +59,7 @@ namespace Internal { struct CustomWizardContext; } -// Factory for creating custom wizards derived from the base classes -// The factory can be registered under a name in CustomWizard. The name can -// be specified in the <wizard class=''...> attribute in the wizard.xml file -// and thus allows for specifying a C++ derived wizard class (see Qt4ProjectManager). - +// Documentation inside. class ICustomWizardFactory { public: virtual CustomWizard *create(const Core::BaseFileWizardParameters& baseFileParameters, @@ -78,10 +74,7 @@ template <class Wizard> class CustomWizardFactory : public ICustomWizardFactory { return new Wizard(baseFileParameters, parent); } }; -// A custom wizard presenting CustomWizardDialog (fields page containing -// path control) for wizards of type "class" or "file". Serves as base class -// for project wizards. - +// Documentation inside. class PROJECTEXPLORER_EXPORT CustomWizard : public Core::BaseFileWizard { Q_OBJECT @@ -137,13 +130,7 @@ private: CustomWizardPrivate *d; }; -// A custom project wizard presenting CustomProjectWizardDialog -// (Project intro page and fields page) for wizards of type "project". -// Overwrites postGenerateFiles() to open the project files according to the -// file attributes. Also inserts '%ProjectName%' into the base -// replacement map once the intro page is left to have it available -// for QLineEdit-type fields' default text. - +// Documentation inside. class PROJECTEXPLORER_EXPORT CustomProjectWizard : public CustomWizard { Q_OBJECT @@ -151,16 +138,12 @@ public: explicit CustomProjectWizard(const Core::BaseFileWizardParameters& baseFileParameters, QObject *parent = 0); - // Can be reimplemented to create custom project wizards. - // initProjectWizardDialog() needs to be called. virtual QWizard *createWizardDialog(QWidget *parent, const QString &defaultPath, const WizardPageList &extensionPages) const; virtual Core::GeneratedFiles generateFiles(const QWizard *w, QString *errorMessage) const; - // Utility to open the projects and editors for the files that have - // the respective attributes set. static bool postGenerateOpen(const Core::GeneratedFiles &l, QString *errorMessage = 0); signals: diff --git a/src/plugins/projectexplorer/customwizard/customwizardpage.cpp b/src/plugins/projectexplorer/customwizard/customwizardpage.cpp index 5cad52c486..0b132c97d9 100644 --- a/src/plugins/projectexplorer/customwizard/customwizardpage.cpp +++ b/src/plugins/projectexplorer/customwizard/customwizardpage.cpp @@ -56,6 +56,18 @@ namespace ProjectExplorer { namespace Internal { // ----------- TextFieldComboBox + +/*! + \class ProjectExplorer::Internal::TextFieldComboBox + \brief A non-editable combo for text editing purposes that plays + with QWizard::registerField (providing a settable 'text' property). + + Allows for a separation of values to be used for wizard fields replacement + and display texts. + + \sa ProjectExplorer::Internal::CustomWizardFieldPage, ProjectExplorer::CustomWizard +*/ + TextFieldComboBox::TextFieldComboBox(QWidget *parent) : QComboBox(parent) { @@ -97,7 +109,15 @@ QString TextFieldComboBox::valueAt(int i) const return i >= 0 && i < count() ? itemData(i, Qt::UserRole).toString() : QString(); } -// -------------- TextCheckBox +/*! + \class ProjectExplorer::Internal::TextFieldCheckBox + \brief A Checkbox that plays with QWizard::registerField. + + Provides a settable 'text' property containing predefined strings for 'true'/'false'). + + \sa ProjectExplorer::Internal::CustomWizardFieldPage, ProjectExplorer::CustomWizard +*/ + TextFieldCheckBox::TextFieldCheckBox(const QString &text, QWidget *parent) : QCheckBox(text, parent), m_trueText(QLatin1String("true")), m_falseText(QLatin1String("false")) @@ -120,7 +140,19 @@ void TextFieldCheckBox::slotStateChanged(int cs) emit textChanged(cs == Qt::Checked ? m_trueText : m_falseText); } -// --------------- CustomWizardFieldPage +/*! + \class ProjectExplorer::Internal::CustomWizardFieldPage + \brief A simple custom wizard page presenting the fields to be used + as page 2 of a BaseProjectWizardDialog if there are any fields. + + Uses the 'field' functionality of QWizard. + Implements validatePage() as the field logic cannot be tied up + with additional validation. Performs checking of the Javascript-based + validation rules of the parameters and displays error messages in a red + warning label. + + \sa ProjectExplorer::CustomWizard +*/ CustomWizardFieldPage::LineEditData::LineEditData(QLineEdit* le, const QString &defText) : lineEdit(le), defaultText(defText) @@ -176,8 +208,11 @@ void CustomWizardFieldPage::clearError() m_errorLabel->setVisible(false); } -// Create widget a control based on the control attributes map -// and register it with the QWizard. +/*! + \brief Create widget a control based on the control attributes map + and register it with the QWizard. +*/ + void CustomWizardFieldPage::addField(const CustomWizardField &field)\ { // Register field, indicate mandatory by '*' (only when registering) @@ -382,7 +417,15 @@ QMap<QString, QString> CustomWizardFieldPage::replacementMap(const QWizard *w, return fieldReplacementMap; } -// --------------- CustomWizardPage +/*! + \class ProjectExplorer::Internal::CustomWizardPage + \brief A custom wizard page presenting the fields to be used and a path chooser + at the bottom (for use by "class"/"file" wizards). + + Does validation on the Path chooser only (as the other fields can by validated by regexps). + + \sa ProjectExplorer::CustomWizard +*/ CustomWizardPage::CustomWizardPage(const QSharedPointer<CustomWizardContext> &ctx, const QSharedPointer<CustomWizardParameters> ¶meters, diff --git a/src/plugins/projectexplorer/customwizard/customwizardpage.h b/src/plugins/projectexplorer/customwizard/customwizardpage.h index 4f3719ebfd..23bb3c83e4 100644 --- a/src/plugins/projectexplorer/customwizard/customwizardpage.h +++ b/src/plugins/projectexplorer/customwizard/customwizardpage.h @@ -56,10 +56,7 @@ struct CustomWizardField; struct CustomWizardParameters; struct CustomWizardContext; -// A non-editable combo for text editing purposes that plays -// with QWizard::registerField (providing a settable 'text' property). -// Allows for a separation of values to be used for wizard fields replacement -// and display texts. +// Documentation inside. class TextFieldComboBox : public QComboBox { Q_PROPERTY(QString text READ text WRITE setText) Q_OBJECT @@ -81,8 +78,7 @@ private: inline QString valueAt(int) const; }; -// A Checkbox that plays with QWizard::registerField (providing a settable -// 'text' property containing predefined strings for 'true'/'false'). +// Documentation inside. class TextFieldCheckBox : public QCheckBox { Q_PROPERTY(QString text READ text WRITE setText) Q_PROPERTY(QString trueText READ trueText WRITE setTrueText) @@ -110,13 +106,7 @@ private: QString m_falseText; }; -// A simple custom wizard page presenting the fields to be used -// as page 2 of a BaseProjectWizardDialog if there are any fields. -// Uses the 'field' functionality of QWizard. -// Implements validatePage() as the field logic cannot be tied up -// with additional validation. Performs checking of the Javascript-based -// validation rules of the parameters and displays error messages in a red -// warning label. +// Documentation inside. class CustomWizardFieldPage : public QWizardPage { Q_OBJECT public: @@ -169,10 +159,7 @@ private: QLabel *m_errorLabel; }; -// A custom wizard page presenting the fields to be used and a path chooser -// at the bottom (for use by "class"/"file" wizards). Does validation on -// the Path chooser only (as the other fields can by validated by regexps). - +// Documentation inside. class CustomWizardPage : public CustomWizardFieldPage { Q_OBJECT public: diff --git a/src/plugins/projectexplorer/customwizard/customwizardparameters.cpp b/src/plugins/projectexplorer/customwizard/customwizardparameters.cpp index 52ba51b1e1..97bfffafa3 100644 --- a/src/plugins/projectexplorer/customwizard/customwizardparameters.cpp +++ b/src/plugins/projectexplorer/customwizard/customwizardparameters.cpp @@ -154,6 +154,20 @@ CustomWizardFile::CustomWizardFile() : { } +/*! + \class ProjectExplorer::CustomWizardValidationRule + \brief A custom wizard validation rule based on JavaScript-expressions over + the field placeholders. + + Placeholder replacement is performed on the condition and it is evaluated + using JavaScript. So, for example '"%ProjectName%" != "untitled" would block + default names. On failure, the message is displayed in a red warning label + in the wizard page. Placeholder replacement is also performed on the message + prior to displaying. + + \sa ProjectExplorer::CustomWizard, ProjectExplorer::CustomWizardFieldPage +*/ + bool CustomWizardValidationRule::validateRules(const QList<CustomWizardValidationRule> &rules, const QMap<QString, QString> &replacementMap, QString *errorMessage) @@ -521,6 +535,16 @@ static inline QString languageSetting() return name; } +/*! + \class ProjectExplorer::Internal::GeneratorScriptArgument + \brief Argument to a custom wizard generator script. + + Contains placeholders to be replaced by field values or file names + as in \c '--class-name=%ClassName%' or \c '--description=%Description%'. + + \sa ProjectExplorer::CustomWizard +*/ + GeneratorScriptArgument::GeneratorScriptArgument(const QString &v) : value(v), flags(0) { @@ -853,6 +877,22 @@ bool replaceFieldHelper(ValueStringTransformation transform, return nonEmptyReplacements; } +/*! + \brief Performs field replacements. + + Replace field values delimited by '%' with special modifiers: + \list + \o %Field% -> simple replacement + \o %Field:l% -> replace with everything changed to lower case + \o %Field:u% -> replace with everything changed to upper case + \o %Field:c% -> replace with first character capitalized + \o %Field:h% -> replace with something usable as header guard + \o %Field:s% -> replace with something usable as structure or class name + \endlist + + The return value indicates whether non-empty replacements were encountered. +*/ + bool CustomWizardContext::replaceFields(const FieldReplacementMap &fm, QString *s) { return replaceFieldHelper(passThrough, fm, s); @@ -897,6 +937,29 @@ QString TemporaryFileTransform::operator()(const QString &value) const return name; } +/*! + \class ProjectExplorer::Internal::CustomWizardContext + \brief Context used for one custom wizard run. + + Shared between CustomWizard and the CustomWizardPage as it is used + for the QLineEdit-type fields' + default texts as well. Contains basic replacement fields + like \c '%CppSourceSuffix%', \c '%CppHeaderSuffix%' (settings-dependent) + reset() should be called before each wizard run to refresh them. + CustomProjectWizard additionally inserts \c '%ProjectName%' from + the intro page to have it available for default texts. + + \sa ProjectExplorer::CustomWizard +*/ + +/*! + \brief Special replaceFields() overload used for the arguments of a generator + script. + + Write the expanded field values out to temporary files and + inserts file names instead of the expanded fields in string 's'. +*/ + bool CustomWizardContext::replaceFields(const FieldReplacementMap &fm, QString *s, TemporaryFilePtrList *files) { diff --git a/src/plugins/projectexplorer/customwizard/customwizardparameters.h b/src/plugins/projectexplorer/customwizard/customwizardparameters.h index 2d8b9df5a3..9915b11356 100644 --- a/src/plugins/projectexplorer/customwizard/customwizardparameters.h +++ b/src/plugins/projectexplorer/customwizard/customwizardparameters.h @@ -75,12 +75,7 @@ struct CustomWizardFile { bool binary; }; -// A validation rule based on Javascript-expressions over the field placeholders. -// Placeholder replacement is performed on the condition and it is evaluated -// using Javascript. So, for example '"%ProjectName%" != "untitled" would block -// default names. On failure, the message is displayed in a red warning label -// in the wizard page. Placeholder replacement is also performed on the message -// prior to displaying. +// Documentation inside. struct CustomWizardValidationRule { // Validate a set of rules and return false + message on the first failing one. static bool validateRules(const QList<CustomWizardValidationRule> &rules, @@ -91,9 +86,7 @@ struct CustomWizardValidationRule { QString message; }; -// Argument to the generator script containing placeholders to -// be replaced by field values or file names -// as in '--class-name=%ClassName%' or '--description=%Description%'. +// Documentation inside. struct GeneratorScriptArgument { enum Flags { // Omit this arguments if all field placeholders expanded to empty strings. @@ -134,14 +127,7 @@ public: int firstPageId; }; -// Context used for one wizard run, shared between CustomWizard -// and the CustomWizardPage as it is used for the QLineEdit-type fields' -// default texts as well. Contains basic replacement fields -// like '%CppSourceSuffix%', '%CppHeaderSuffix%' (settings-dependent) -// reset() should be called before each wizard run to refresh them. -// CustomProjectWizard additionally inserts '%ProjectName%' from -// the intro page to have it available for default texts. - +// Documentation inside. struct CustomWizardContext { typedef QMap<QString, QString> FieldReplacementMap; typedef QSharedPointer<QTemporaryFile> TemporaryFilePtr; @@ -149,20 +135,7 @@ struct CustomWizardContext { void reset(); - // Replace field values delimited by '%' with special modifiers: - // %Field% -> simple replacement - // %Field:l% -> replace with everything changed to lower case - // %Field:u% -> replace with everything changed to upper case - // %Field:c% -> replace with first character capitalized - // %Field:h% -> replace with something usable as header guard - // %Field:s% -> replace with something usable as structure or class name - // The return value indicates whether non-empty - // replacements were encountered. static bool replaceFields(const FieldReplacementMap &fm, QString *s); - - // Special replaceFields() overload used for the arguments of a generator - // script: Write the expanded field values out to temporary files and - // inserts file names instead of the expanded fields in string 's'. static bool replaceFields(const FieldReplacementMap &fm, QString *s, TemporaryFilePtrList *files); diff --git a/src/plugins/projectexplorer/customwizard/customwizardpreprocessor.cpp b/src/plugins/projectexplorer/customwizard/customwizardpreprocessor.cpp index 408f83c833..5b820a486b 100644 --- a/src/plugins/projectexplorer/customwizard/customwizardpreprocessor.cpp +++ b/src/plugins/projectexplorer/customwizard/customwizardpreprocessor.cpp @@ -188,7 +188,7 @@ bool PreprocessContext::process(const QString &in, QString *out, QString *errorM *errorMessage = msgEmptyStack(l); return false; } - QString expression; + QString expression; bool expressionValue = false; PreprocessStackEntry &top = m_sectionStack.back(); @@ -258,6 +258,26 @@ bool PreprocessContext::process(const QString &in, QString *out, QString *errorM return true; } +/*! + \brief Custom wizard preprocessor based on JavaScript expressions. + + Preprocess a string using simple syntax: + \code +Text +@if <JavaScript-expression> +Bla... +@elsif <JavaScript-expression2> +Blup +@endif +\endcode + + The JavaScript-expressions must evaluate to integers or boolean, like + \c '2 == 1 + 1', \c '"a" == "a"'. The variables of the custom wizard will be + expanded before, so , \c "%VAR%" should be used for strings and \c %VAR% for integers. + + \sa ProjectExplorer::CustomWizard +*/ + bool customWizardPreprocess(const QString &in, QString *out, QString *errorMessage) { PreprocessContext context; diff --git a/src/plugins/projectexplorer/customwizard/customwizardpreprocessor.h b/src/plugins/projectexplorer/customwizard/customwizardpreprocessor.h index 25339749bc..e58a7f29c6 100644 --- a/src/plugins/projectexplorer/customwizard/customwizardpreprocessor.h +++ b/src/plugins/projectexplorer/customwizard/customwizardpreprocessor.h @@ -40,21 +40,6 @@ QT_FORWARD_DECLARE_CLASS(QScriptEngine) namespace ProjectExplorer { namespace Internal { -/* Preprocess a string using simple syntax: \code - -Text -@if <JavaScript-expression> -Bla... -@elsif <JavaScript-expression2> -Blup -@endif -\endcode - -* JavaScript-expressions must evaluate to integers or boolean, like -* '2 == 1 + 1', '"a" == "a"'. The variables of the custom wizard will be -* expanded beforem, so , "%VAR%" should be used for strings and %VAR% for integers. -*/ - bool customWizardPreprocess(const QString &in, QString *out, QString *errorMessage); /* Helper to evaluate an expression. */ bool evaluateBooleanJavaScriptExpression(QScriptEngine &engine, const QString &expression, bool *result, QString *errorMessage); diff --git a/src/plugins/projectexplorer/customwizard/customwizardscriptgenerator.cpp b/src/plugins/projectexplorer/customwizard/customwizardscriptgenerator.cpp index 889f08cfa9..9b3b4ee165 100644 --- a/src/plugins/projectexplorer/customwizard/customwizardscriptgenerator.cpp +++ b/src/plugins/projectexplorer/customwizard/customwizardscriptgenerator.cpp @@ -149,7 +149,13 @@ static bool return true; } -// Do a dry run of the generation script to get a list of files +/*! + \brief Custom wizard script generator function (Step1) - dry run. + + Do a dry run of the generation script to get a list of files + \sa runCustomWizardGeneratorScript, ProjectExplorer::CustomWizard +*/ + Core::GeneratedFiles dryRunCustomWizardGeneratorScript(const QString &targetPath, const QStringList &script, @@ -203,6 +209,37 @@ Core::GeneratedFiles return files; } +/*! + \brief Custom wizard script generator function (Step2) - actual file creation. + + In addition to the <file> elements + that define template files in which macros are replaced, it is possible to have + a custom wizard call a generation script (specified in the "generatorscript" + attribute of the <files> element) which actually creates files. + The command line of the script must follow the convention + \code + script [--dry-run] [options] + \endcode + + Options containing field placeholders are configured in the XML files + and will be passed with them replaced by their values. + + As Qt Creator needs to know the file names before actually creates them to + do overwrite checking etc., this is 2-step process: + \list + \o Determine file names and attributes: The script is called with the + \c --dry-run option and the field values. It then prints the relative path + names it intends to create followed by comma-separated attributes + matching those of the \c <file> element, for example: + \c myclass.cpp,openeditor + \o The script is called with the parameters only in the working directory + and then actually creates the files. If that involves directories, the script + should create those, too. + \endlist + + \sa dryRunCustomWizardGeneratorScript, ProjectExplorer::CustomWizard + */ + bool runCustomWizardGeneratorScript(const QString &targetPath, const QStringList &script, const QList<GeneratorScriptArgument> &arguments, diff --git a/src/plugins/projectexplorer/customwizard/customwizardscriptgenerator.h b/src/plugins/projectexplorer/customwizard/customwizardscriptgenerator.h index e41c027351..3eea52f2f1 100644 --- a/src/plugins/projectexplorer/customwizard/customwizardscriptgenerator.h +++ b/src/plugins/projectexplorer/customwizard/customwizardscriptgenerator.h @@ -45,29 +45,6 @@ namespace Internal { struct GeneratorScriptArgument; -/* Custom wizard script generator functions. In addition to the <file> elements - * that define template files in which macros are replaced, it is possible to have - * a custom wizard call a generation script (specified in the "generatorscript" - * attribute of the <files> element) which actually creates files. - * The command line of the script must follow the convention - * - * script [--dry-run] [options] - * - * Options containing field placeholders are configured in the XML files - * and will be passed with them replaced by their values. - * - * As Qt Creator needs to know the file names before actually creates them to - * do overwrite checking etc., this is 2-step process: - * 1) Determine file names and attributes: The script is called with the - * --dry-run option and the field values. It then prints the relative path - * names it intends to create followed by comma-separated attributes - * matching those of the <file> element, for example: - * myclass.cpp,openeditor - * 2) The script is called with the parameters only in the working directory - * and then actually creates the files. If that involves directories, the script - * should create those, too. - */ - // Parse the script arguments apart and expand the binary. QStringList fixGeneratorScript(const QString &configFile, QString attributeIn); diff --git a/src/plugins/projectexplorer/deployconfigurationmodel.cpp b/src/plugins/projectexplorer/deployconfigurationmodel.cpp index d5f69eb944..1d0981ce6d 100644 --- a/src/plugins/projectexplorer/deployconfigurationmodel.cpp +++ b/src/plugins/projectexplorer/deployconfigurationmodel.cpp @@ -36,9 +36,14 @@ using namespace ProjectExplorer; -/// -/// DeployConfigurationsModel -/// +/*! + \class ProjectExplorer::DeployConfigurationModel + + \brief A model to represent the run configurations of a target. + + To be used in for the drop down of comboboxes. Does automatically adjust + itself to added and removed DeployConfigurations +*/ class DeployConfigurationComparer { diff --git a/src/plugins/projectexplorer/deployconfigurationmodel.h b/src/plugins/projectexplorer/deployconfigurationmodel.h index 1338a52160..348ec56740 100644 --- a/src/plugins/projectexplorer/deployconfigurationmodel.h +++ b/src/plugins/projectexplorer/deployconfigurationmodel.h @@ -40,10 +40,7 @@ namespace ProjectExplorer { class Target; class DeployConfiguration; -/*! A model to represent the run configurations of a target. - To be used in for the drop down of comboboxes - Does automatically adjust itself to added and removed RunConfigurations -*/ +// Documentation inside. class DeployConfigurationModel : public QAbstractListModel { Q_OBJECT diff --git a/src/plugins/projectexplorer/ioutputparser.cpp b/src/plugins/projectexplorer/ioutputparser.cpp index 406119f32c..c0145207f2 100644 --- a/src/plugins/projectexplorer/ioutputparser.cpp +++ b/src/plugins/projectexplorer/ioutputparser.cpp @@ -35,6 +35,84 @@ #include <utils/qtcassert.h> +/*! + \class ProjectExplorer::IOutputParser + + \brief Interface for an output parser that emit build issues (tasks). + + \sa ProjectExplorer::Task +*/ + +/*! + \fn void ProjectExplorer::IOutputParser::appendOutputParser(IOutputParser *parser) + + \brief Append a subparser to this parser, of which IOutputParser will take ownership. +*/ + +/*! + \fn IOutputParser *ProjectExplorer::IOutputParser::takeOutputParserChain() + + \brief Remove the appended outputparser chain from this parser, transferring + ownership of the parser chain to the caller. +*/ + +/*! + \fn IOutputParser *ProjectExplorer::IOutputParser::childParser() const + + \brief Return the head of this parsers output parser children, IOutputParser keeps ownership. +*/ + +/*! + \fn void ProjectExplorer::IOutputParser::stdOutput(const QString &line) + + \brief Called once for each line if standard output to parse. +*/ + +/*! + \fn void ProjectExplorer::IOutputParser::stdError(const QString &line) + + \brief Called once for each line if standard error to parse. +*/ + +/*! + \fn bool ProjectExplorer::IOutputParser::hasFatalErrors() const + + \brief This is mainly a symbian specific quirk. +*/ + +/*! + \fn void ProjectExplorer::IOutputParser::addOutput(const QString &string, ProjectExplorer::BuildStep::OutputFormat format) + + \brief Should be emitted whenever some additional information should be added to the output. + + Note: This is additional information. There is no need to add each line! +*/ + +/*! + \fn void ProjectExplorer::IOutputParser::addTask(const ProjectExplorer::Task &task) + + \brief Should be emitted for each task seen in the output. +*/ + +/*! + \fn void ProjectExplorer::IOutputParser::outputAdded(const QString &string, ProjectExplorer::BuildStep::OutputFormat format) + + \brief Subparsers have their addOutput signal connected to this slot. +*/ + +/*! + \fn void ProjectExplorer::IOutputParser::outputAdded(const QString &string, ProjectExplorer::BuildStep::OutputFormat format) + + \brief This method can be overwritten to change the string. +*/ + +/*! + \fn void ProjectExplorer::IOutputParser::taskAdded(const ProjectExplorer::Task &task) + + \brief Subparsers have their addTask signal connected to this slot. + This method can be overwritten to change the task. +*/ + namespace ProjectExplorer { IOutputParser::IOutputParser() : m_parser(0) diff --git a/src/plugins/projectexplorer/ioutputparser.h b/src/plugins/projectexplorer/ioutputparser.h index c2b5c55fdd..5140003037 100644 --- a/src/plugins/projectexplorer/ioutputparser.h +++ b/src/plugins/projectexplorer/ioutputparser.h @@ -41,6 +41,7 @@ namespace ProjectExplorer { class Task; +// Documentation inside. class PROJECTEXPLORER_EXPORT IOutputParser : public QObject { Q_OBJECT @@ -48,44 +49,26 @@ public: IOutputParser(); virtual ~IOutputParser(); - /// Append a subparser to this parser. - /// IOutputParser will take ownership. virtual void appendOutputParser(IOutputParser *parser); - /// Remove the appended outputparser chain frm this parser. - /// This method transferes ownership of the parser chain to the caller! IOutputParser *takeOutputParserChain(); - /// Return the head of this parsers output parser children - /// IOutputParser keeps ownership! IOutputParser *childParser() const; void setChildParser(IOutputParser *parser); - /// Called once for each line if standard output to parse. virtual void stdOutput(const QString &line); - /// Called once for each line if standard error to parse. virtual void stdError(const QString &line); - // This is mainly a symbian specific quirk virtual bool hasFatalErrors() const; // For GnuMakeParser virtual void setWorkingDirectory(const QString &workingDirectory); signals: - /// Should be emitted whenever some additional information should be - /// added to the output. - /// Note: This is additional information. There is no need to add each - /// line! void addOutput(const QString &string, ProjectExplorer::BuildStep::OutputFormat format); - /// Should be emitted for each task seen in the output. void addTask(const ProjectExplorer::Task &task); public slots: - /// Subparsers have their addOutput signal connected to this slot. - /// This method can be overwritten to change the string. virtual void outputAdded(const QString &string, ProjectExplorer::BuildStep::OutputFormat format); - /// Subparsers have their addTask signal connected to this slot. - /// This method can be overwritten to change the task. virtual void taskAdded(const ProjectExplorer::Task &task); private: diff --git a/src/plugins/projectexplorer/pluginfilefactory.cpp b/src/plugins/projectexplorer/pluginfilefactory.cpp index 928ea66289..6c618291ae 100644 --- a/src/plugins/projectexplorer/pluginfilefactory.cpp +++ b/src/plugins/projectexplorer/pluginfilefactory.cpp @@ -47,6 +47,12 @@ using namespace ProjectExplorer; using namespace ProjectExplorer::Internal; +/*! + \class ProjectExplorer::Internal::ProjectFileFactory + + \brief Factory for project files. +*/ + ProjectFileFactory::ProjectFileFactory(IProjectManager *manager) : m_mimeTypes(manager->mimeType()), m_manager(manager) diff --git a/src/plugins/projectexplorer/pluginfilefactory.h b/src/plugins/projectexplorer/pluginfilefactory.h index 61fd0d7bfe..5e956564d4 100644 --- a/src/plugins/projectexplorer/pluginfilefactory.h +++ b/src/plugins/projectexplorer/pluginfilefactory.h @@ -44,8 +44,6 @@ class ProjectExplorerPlugin; namespace Internal { -/* Factory for project files. */ - class ProjectFileFactory : public Core::IFileFactory { Q_OBJECT diff --git a/src/plugins/projectexplorer/processparameters.cpp b/src/plugins/projectexplorer/processparameters.cpp index 1ba78977ae..2824686c1c 100644 --- a/src/plugins/projectexplorer/processparameters.cpp +++ b/src/plugins/projectexplorer/processparameters.cpp @@ -38,6 +38,18 @@ #include <QtCore/QFileInfo> #include <QtCore/QDir> +/*! + \class ProjectExplorer::ProcessParameters + + \brief ProcessParameters aggregates all parameters needed to start a process. + + It offers a set of functions which expand macros and environment variables + inside the raw parameters to obtain final values for starting a process + or for display purposes. + + \sa ProjectExplorer::AbstractProcessStep +*/ + using namespace ProjectExplorer; ProcessParameters::ProcessParameters() : @@ -46,24 +58,55 @@ ProcessParameters::ProcessParameters() : { } +/*! + \brief Sets the executable to run. +*/ + void ProcessParameters::setCommand(const QString &cmd) { m_command = cmd; m_effectiveCommand.clear(); } +/*! + \brief Sets the command line arguments used by the process +*/ + void ProcessParameters::setArguments(const QString &arguments) { m_arguments = arguments; m_effectiveArguments.clear(); } +/*! + \brief Sets the workingDirectory for the process for a buildConfiguration + should be called from init() +*/ + void ProcessParameters::setWorkingDirectory(const QString &workingDirectory) { m_workingDirectory = workingDirectory; m_effectiveWorkingDirectory.clear(); } +/*! + \fn void ProjectExplorer::ProcessParameters::setEnvironment(const Utils::Environment &env) + \brief Set the Environment for running the command + + Should be called from init() +*/ + +/*! + \fn void ProjectExplorer::ProcessParameters::setMacroExpander(Utils::AbstractMacroExpander *mx) + \brief Set the macro expander to use on the command, arguments and working dir. + + Note that the caller retains ownership of the object. +*/ + +/*! + \brief Get the fully expanded working directory. +*/ + QString ProcessParameters::effectiveWorkingDirectory() const { if (m_effectiveWorkingDirectory.isEmpty()) { @@ -75,6 +118,10 @@ QString ProcessParameters::effectiveWorkingDirectory() const return m_effectiveWorkingDirectory; } +/*! + \brief Get the fully expanded command name to run +*/ + QString ProcessParameters::effectiveCommand() const { if (m_effectiveCommand.isEmpty()) { @@ -90,6 +137,10 @@ QString ProcessParameters::effectiveCommand() const return m_effectiveCommand; } +/*! + \brief True if effectiveCommand() would return only a fallback. +*/ + bool ProcessParameters::commandMissing() const { effectiveCommand(); diff --git a/src/plugins/projectexplorer/processparameters.h b/src/plugins/projectexplorer/processparameters.h index 0723d33bb5..94a875d960 100644 --- a/src/plugins/projectexplorer/processparameters.h +++ b/src/plugins/projectexplorer/processparameters.h @@ -43,39 +43,24 @@ class AbstractMacroExpander; namespace ProjectExplorer { -/*! - ProcessParameters aggregates all parameters needed to start a process. - - It offers a set of functions which expand macros and environment variables - inside the raw parameters to obtain final values for starting a process - or for display purposes. -*/ - +// Documentation inside. class PROJECTEXPLORER_EXPORT ProcessParameters { public: ProcessParameters(); - /// setCommand() sets the executable to run void setCommand(const QString &cmd); QString command() const { return m_command; } - /// sets the command line arguments used by the process void setArguments(const QString &arguments); QString arguments() const { return m_arguments; } - /// sets the workingDirectory for the process for a buildConfiguration - /// should be called from init() void setWorkingDirectory(const QString &workingDirectory); QString workingDirectory() const { return m_workingDirectory; } - /// Set the Environment for running the command - /// should be called from init() void setEnvironment(const Utils::Environment &env) { m_environment = env; } Utils::Environment environment() const { return m_environment; } - /// Set the macro expander to use on the command, arguments and working dir. - /// Note that the caller retains ownership of the object. void setMacroExpander(Utils::AbstractMacroExpander *mx) { m_macroExpander = mx; } Utils::AbstractMacroExpander *macroExpander() const { return m_macroExpander; } diff --git a/src/plugins/projectexplorer/project.cpp b/src/plugins/projectexplorer/project.cpp index a9344b164d..0cc0b220a3 100644 --- a/src/plugins/projectexplorer/project.cpp +++ b/src/plugins/projectexplorer/project.cpp @@ -46,6 +46,26 @@ #include <limits> #include <utils/qtcassert.h> +/*! + \class ProjectExplorer::Project + + \brief A project. +*/ + +/*! + \fn void ProjectExplorer::Project::environmentChanged() + + \brief Convenience signal emitted if the activeBuildConfiguration emits environmentChanged + or if the activeBuildConfiguration changes (including due to the active target changing). +*/ + +/*! + \fn void ProjectExplorer::Project::buildConfigurationEnabledChanged() + + \brief Convenience signal emitted if the activeBuildConfiguration emits isEnabledChanged() + or if the activeBuildConfiguration changes (including due to the active target changing). +*/ + namespace { const char * const ACTIVE_TARGET_KEY("ProjectExplorer.Project.ActiveTarget"); const char * const TARGET_KEY_PREFIX("ProjectExplorer.Project.Target."); @@ -211,6 +231,17 @@ QList<BuildConfigWidget*> Project::subConfigWidgets() return QList<BuildConfigWidget*>(); } +/*! + \brief Serialize all data into a QVariantMap. + + This map is then saved in the .user file of the project. + Just put all your data into the map. + + \note Do not forget to call your base class' toMap method. + \note Do not forget to call setActiveBuildConfiguration when + creating new BuilConfigurations. +*/ + QVariantMap Project::toMap() const { const QList<Target *> ts = targets(); diff --git a/src/plugins/projectexplorer/project.h b/src/plugins/projectexplorer/project.h index 8de8709e92..e37189f151 100644 --- a/src/plugins/projectexplorer/project.h +++ b/src/plugins/projectexplorer/project.h @@ -53,6 +53,7 @@ class ProjectNode; class Target; class ProjectPrivate; +// Documentation inside. class PROJECTEXPLORER_EXPORT Project : public QObject { @@ -104,14 +105,6 @@ public: static QString makeUnique(const QString &preferedName, const QStringList &usedNames); - // Serialize all data into a QVariantMap. This map is then saved - // in the .user file of the project. - // - // Just put all your data into the map. - // - // Note: Do not forget to call your base class' toMap method. - // Note: Do not forget to call setActiveBuildConfiguration when - // creating new BuilConfigurations. virtual QVariantMap toMap() const; // The directory that holds the project file. This includes the absolute path. @@ -131,14 +124,7 @@ signals: void removedTarget(ProjectExplorer::Target *target); void addedTarget(ProjectExplorer::Target *target); - /// convenience signal emitted if the activeBuildConfiguration emits environmentChanged - /// or if the activeBuildConfiguration changes - /// (including due to the active target changing). void environmentChanged(); - - /// convenience signal emitted if the activeBuildConfiguration emits isEnabledChanged() - /// or if the activeBuildConfiguration changes - /// (including due to the active target changing). void buildConfigurationEnabledChanged(); protected: diff --git a/src/plugins/projectexplorer/projectexplorer.cpp b/src/plugins/projectexplorer/projectexplorer.cpp index 1bc69e2ea5..88548e740a 100644 --- a/src/plugins/projectexplorer/projectexplorer.cpp +++ b/src/plugins/projectexplorer/projectexplorer.cpp @@ -127,6 +127,24 @@ #include <QtGui/QMainWindow> #include <QtGui/QWizard> +/*! + \namespace ProjectExplorer + ProjectExplorer plugin namespace +*/ + +/*! + \namespace ProjectExplorer::Internal + Internal namespace of the ProjectExplorer plugin + \internal +*/ + +/*! + \class ProjectExplorer::ProjectExplorerPlugin + + \brief ProjectExplorerPlugin with static accessor and utility functions to obtain + current project, open projects, etc. +*/ + Q_DECLARE_METATYPE(Core::IEditorFactory*) Q_DECLARE_METATYPE(Core::IExternalEditor*) diff --git a/src/plugins/projectexplorer/projectexplorersettingspage.h b/src/plugins/projectexplorer/projectexplorersettingspage.h index a083868dda..d7e0ef1cd0 100644 --- a/src/plugins/projectexplorer/projectexplorersettingspage.h +++ b/src/plugins/projectexplorer/projectexplorersettingspage.h @@ -43,6 +43,7 @@ namespace Internal { struct ProjectExplorerSettings; +// Documentation inside. class ProjectExplorerSettingsWidget : public QWidget { Q_OBJECT public: diff --git a/src/plugins/projectexplorer/projectfilewizardextension.cpp b/src/plugins/projectexplorer/projectfilewizardextension.cpp index 0eef8db4a6..39966556ca 100644 --- a/src/plugins/projectexplorer/projectfilewizardextension.cpp +++ b/src/plugins/projectexplorer/projectfilewizardextension.cpp @@ -54,6 +54,21 @@ #include <QtCore/QMultiMap> #include <QtCore/QDir> +/*! + \class ProjectExplorer::Internal::ProjectFileWizardExtension + + \brief Post-file generating steps of a project wizard. + + Offers: + \list + \o Add to a project file (*.pri/ *.pro) + \o Initialize a version control repository (unless the path is already + managed) and do 'add' if the VCS supports it. + \endlist + + \sa ProjectExplorer::Internal::ProjectWizardPage +*/ + enum { debugExtension = 0 }; namespace ProjectExplorer { diff --git a/src/plugins/projectexplorer/projectfilewizardextension.h b/src/plugins/projectexplorer/projectfilewizardextension.h index ec910fc974..ba27a21e89 100644 --- a/src/plugins/projectexplorer/projectfilewizardextension.h +++ b/src/plugins/projectexplorer/projectfilewizardextension.h @@ -41,10 +41,6 @@ namespace Internal { struct ProjectWizardContext; -/* Final file wizard processing steps: - * 1) Add to a project file (*.pri/ *.pro) - * 2) Initialize a version control repository (unless the path is already - * managed) and do 'add' if the VCS supports it. */ class ProjectFileWizardExtension : public Core::IFileWizardExtension { Q_OBJECT diff --git a/src/plugins/projectexplorer/projectnodes.cpp b/src/plugins/projectexplorer/projectnodes.cpp index 73808575db..dcf24a5a92 100644 --- a/src/plugins/projectexplorer/projectnodes.cpp +++ b/src/plugins/projectexplorer/projectnodes.cpp @@ -48,14 +48,20 @@ using namespace ProjectExplorer; /*! - \class FileNode + \class ProjectExplorer::Node - Base class of all nodes in the node hierarchy. + \brief Base class of all nodes in the node hierarchy. - \see FileNode - \see FolderNode - \see ProjectNode + The nodes are arranged in a tree where leaves are FileNodes and non-leaves are FolderNodes + A Project is a special Folder that manages the files and normal folders underneath it. + + The Watcher emits signals for structural changes in the hierarchy. + A Visitor can be used to traverse all Projects and other Folders. + + \sa ProjectExplorer::FileNode, ProjectExplorer::FolderNode, ProjectExplorer::ProjectNode + \sa ProjectExplorer::NodesWatcher, ProjectExplorer::NodesVisitor */ + Node::Node(NodeType nodeType, const QString &filePath) : QObject(), @@ -73,7 +79,7 @@ NodeType Node::nodeType() const } /*! - Project that owns & manages the node. It's the first project in list of ancestors. + \brief Project that owns & manages the node. It's the first project in list of ancestors. */ ProjectNode *Node::projectNode() const { @@ -81,7 +87,7 @@ ProjectNode *Node::projectNode() const } /*! - Parent in node hierarchy. + \brief Parent in node hierarchy. */ FolderNode *Node::parentFolderNode() const { @@ -89,7 +95,7 @@ FolderNode *Node::parentFolderNode() const } /*! - Path of file or folder in the filesystem the node represents. + \brief Path of file or folder in the filesystem the node represents. */ QString Node::path() const { @@ -117,12 +123,11 @@ void Node::setPath(const QString &path) } /*! - \class FileNode + \class ProjectExplorer::FileNode - In-memory presentation of a file. All FileNode's are leaf nodes. + \brief In-memory presentation of a file. All FileNode's are leaf nodes. - \see FolderNode - \see ProjectNode + \sa ProjectExplorer::FolderNode, ProjectExplorer::ProjectNode */ FileNode::FileNode(const QString &filePath, @@ -140,7 +145,7 @@ FileType FileNode::fileType() const } /*! - Returns true if the file is automatically generated by a compile step. + \brief Returns true if the file is automatically generated by a compile step. */ bool FileNode::isGenerated() const { @@ -148,12 +153,11 @@ bool FileNode::isGenerated() const } /*! - \class FolderNode + \class ProjectExplorer::FolderNode In-memory presentation of a folder. Note that the node itself + all children (files and folders) are "managed" by the owning project. - \see FileNode - \see ProjectNode + \sa ProjectExplorer::FileNode, ProjectExplorer::ProjectNode */ FolderNode::FolderNode(const QString &folderPath) : Node(FolderNodeType, folderPath), @@ -167,20 +171,19 @@ FolderNode::~FolderNode() qDeleteAll(m_fileNodes); } -/* - The display name that should be used in a view. - - - \see setFolderName() +/*! + \brief The display name that should be used in a view. + \sa setFolderName() */ + QString FolderNode::displayName() const { return m_displayName; } -/* - The icon that should be used in a view. Default is the directory icon (QStyle::S_PDirIcon). - \see setIcon() +/*! + \brief The icon that should be used in a view. Default is the directory icon (QStyle::S_PDirIcon). + s\a setIcon() */ QIcon FolderNode::icon() const { @@ -218,17 +221,17 @@ void FolderNode::setIcon(const QIcon &icon) } /*! - \class ProjectNode + \class ProjectExplorer::ProjectNode + + \brief In-memory presentation of a Project. - In-memory presentation of a Project. A concrete subclass must implement the "persistent" stuff - \see FileNode - \see FolderNode + \sa ProjectExplorer::FileNode, ProjectExplorer::FolderNode */ -/* - Creates uninitialized ProjectNode object. +/*! + \brief Creates uninitialized ProjectNode object. */ ProjectNode::ProjectNode(const QString &projectFilePath) : FolderNode(projectFilePath) @@ -287,10 +290,12 @@ QList<NodesWatcher*> ProjectNode::watchers() const return m_watchers; } -/* - Registers a watcher for the current project & all sub projects +/*! + \brief Registers a watcher for the current project & all sub projects + It does not take ownership of the watcher. - */ +*/ + void ProjectNode::registerWatcher(NodesWatcher *watcher) { if (!watcher) @@ -302,8 +307,8 @@ void ProjectNode::registerWatcher(NodesWatcher *watcher) subProject->registerWatcher(watcher); } -/* - Removes a watcher for the current project & all sub projects. +/*! + \brief Removes a watcher for the current project & all sub projects. */ void ProjectNode::unregisterWatcher(NodesWatcher *watcher) { @@ -323,7 +328,7 @@ void ProjectNode::accept(NodesVisitor *visitor) } /*! - Adds project nodes to the hierarchy and emits the corresponding signals. + \brief Adds project nodes to the hierarchy and emits the corresponding signals. */ void ProjectNode::addProjectNodes(const QList<ProjectNode*> &subProjects) { @@ -355,9 +360,11 @@ void ProjectNode::addProjectNodes(const QList<ProjectNode*> &subProjects) } /*! - Remove project nodes from the hierarchy and emits the corresponding signals. + \brief Remove project nodes from the hierarchy and emits the corresponding signals. + All objects in the argument list are deleted. - */ +*/ + void ProjectNode::removeProjectNodes(const QList<ProjectNode*> &subProjects) { if (!subProjects.isEmpty()) { @@ -394,8 +401,8 @@ void ProjectNode::removeProjectNodes(const QList<ProjectNode*> &subProjects) } /*! - Adds folder nodes to the hierarchy and emits the corresponding signals. - */ + \brief Adds folder nodes to the hierarchy and emits the corresponding signals. +*/ void ProjectNode::addFolderNodes(const QList<FolderNode*> &subFolders, FolderNode *parentFolder) { Q_ASSERT(parentFolder); @@ -444,9 +451,10 @@ void ProjectNode::addFolderNodes(const QList<FolderNode*> &subFolders, FolderNod } /*! - Remove file nodes from the hierarchy and emits the corresponding signals. + \brief Remove file nodes from the hierarchy and emits the corresponding signals. + All objects in the subFolders list are deleted. - */ +*/ void ProjectNode::removeFolderNodes(const QList<FolderNode*> &subFolders, FolderNode *parentFolder) { @@ -483,9 +491,11 @@ void ProjectNode::removeFolderNodes(const QList<FolderNode*> &subFolders, } /*! - Adds file nodes to the internal list and emits the corresponding signals. + \brief Adds file nodes to the internal list and emits the corresponding signals. + This method should be called within an implementation of the public method addFiles. - */ +*/ + void ProjectNode::addFileNodes(const QList<FileNode*> &files, FolderNode *folder) { Q_ASSERT(folder); @@ -530,10 +540,12 @@ void ProjectNode::addFileNodes(const QList<FileNode*> &files, FolderNode *folder } /*! - Remove file nodes from the internal list and emits the corresponding signals. + \brief Remove file nodes from the internal list and emits the corresponding signals. + All objects in the argument list are deleted. This method should be called within an implementation of the public method removeFiles. - */ +*/ + void ProjectNode::removeFileNodes(const QList<FileNode*> &files, FolderNode *folder) { Q_ASSERT(folder); @@ -573,14 +585,14 @@ void ProjectNode::watcherDestroyed(QObject *watcher) } /*! - Sort pointers to FileNodes - */ + \brief Sort pointers to FileNodes +*/ bool ProjectNode::sortNodesByPath(Node *n1, Node *n2) { return n1->path() < n2->path(); } /*! - \class SessionNode + \class ProjectExplorer::SessionNode */ SessionNode::SessionNode(const QString &sessionPath, QObject *parentObject) @@ -595,10 +607,11 @@ QList<NodesWatcher*> SessionNode::watchers() const return m_watchers; } -/* - Registers a watcher for the complete session tree. +/*! + \brief Registers a watcher for the complete session tree. It does not take ownership of the watcher. */ + void SessionNode::registerWatcher(NodesWatcher *watcher) { if (!watcher) @@ -610,9 +623,10 @@ void SessionNode::registerWatcher(NodesWatcher *watcher) project->registerWatcher(watcher); } -/* - Removes a watcher from the complete session tree +/*! + \brief Removes a watcher from the complete session tree */ + void SessionNode::unregisterWatcher(NodesWatcher *watcher) { if (!watcher) @@ -699,9 +713,9 @@ void SessionNode::watcherDestroyed(QObject *watcher) } /*! - \class NodesWatcher + \class ProjectExplorer::NodesWatcher - NodesWatcher let you keep track of changes in the tree. + \brief NodesWatcher lets you keep track of changes in the tree. Add a watcher by calling ProjectNode::registerWatcher() or SessionNode::registerWatcher(). Whenever the tree underneath the @@ -711,8 +725,10 @@ void SessionNode::watcherDestroyed(QObject *watcher) by calling ProjectNode::unregisterWatcher and SessionNode::unregisterWatcher(). - The NodesWatcher is similar to the Observer in the + The NodesWatcher is similar to the Observer in the well-known Observer pattern (Booch et al). + + \sa ProjectExplorer::Node */ NodesWatcher::NodesWatcher(QObject *parent) diff --git a/src/plugins/projectexplorer/projectnodes.h b/src/plugins/projectexplorer/projectnodes.h index f4047a3492..95b084d50c 100644 --- a/src/plugins/projectexplorer/projectnodes.h +++ b/src/plugins/projectexplorer/projectnodes.h @@ -52,16 +52,6 @@ namespace Core { namespace ProjectExplorer { -// -// = Node hierarchy = -// -// The nodes are arranged in a tree where leaves are FileNodes and non-leaves are FolderNodes -// A Project is a special Folder that manages the files and normal folders underneath it. -// -// The Watcher emits signals for structural changes in the hierarchy. -// A Visitor can be used to traverse all Projects and other Folders. -// - enum NodeType { FileNodeType = 1, FolderNodeType, @@ -89,6 +79,7 @@ class ProjectNode; class NodesWatcher; class NodesVisitor; +// Documentation inside. class PROJECTEXPLORER_EXPORT Node : public QObject { Q_OBJECT public: @@ -128,6 +119,7 @@ private: bool m_generated; }; +// Documentation inside. class PROJECTEXPLORER_EXPORT FolderNode : public Node { Q_OBJECT public: @@ -156,6 +148,7 @@ private: mutable QIcon m_icon; }; +// Documentation inside. class PROJECTEXPLORER_EXPORT ProjectNode : public FolderNode { Q_OBJECT @@ -250,6 +243,7 @@ private: friend class SessionNode; }; +// Documentation inside. class PROJECTEXPLORER_EXPORT SessionNode : public FolderNode { Q_OBJECT public: @@ -275,6 +269,7 @@ private: QList<NodesWatcher*> m_watchers; }; +// Documentation inside. class PROJECTEXPLORER_EXPORT NodesWatcher : public QObject { Q_OBJECT public: diff --git a/src/plugins/projectexplorer/projectwelcomepagewidget.cpp b/src/plugins/projectexplorer/projectwelcomepagewidget.cpp index 774234a9f2..a4f997b802 100644 --- a/src/plugins/projectexplorer/projectwelcomepagewidget.cpp +++ b/src/plugins/projectexplorer/projectwelcomepagewidget.cpp @@ -58,6 +58,12 @@ # define MAX_RECENT_SESSION_ITEMS 9 #endif +/*! + \class ProjectExplorer::Internal::ProjectWelcomePageWidget + + \brief Welcome page listing projects and sessions. +*/ + using namespace ProjectExplorer::Internal; bool ProjectWelcomePageWidget::WelcomePageData::operator==(const WelcomePageData &rhs) const diff --git a/src/plugins/projectexplorer/projectwelcomepagewidget.h b/src/plugins/projectexplorer/projectwelcomepagewidget.h index a9e9751ec1..2ce15b9d51 100644 --- a/src/plugins/projectexplorer/projectwelcomepagewidget.h +++ b/src/plugins/projectexplorer/projectwelcomepagewidget.h @@ -44,6 +44,7 @@ namespace Ui { class ProjectWelcomePageWidget; } +// Documentation inside. class ProjectWelcomePageWidget : public QWidget { Q_OBJECT diff --git a/src/plugins/projectexplorer/projectwizardpage.cpp b/src/plugins/projectexplorer/projectwizardpage.cpp index cf1876880f..602b714082 100644 --- a/src/plugins/projectexplorer/projectwizardpage.cpp +++ b/src/plugins/projectexplorer/projectwizardpage.cpp @@ -36,6 +36,14 @@ #include <QtCore/QDir> #include <QtCore/QTextStream> +/*! + \class ProjectExplorer::Internal::ProjectWizardPage + + \brief Wizard page showing projects and version control to add new files to. + + \sa ProjectExplorer::Internal::ProjectFileWizardExtension +*/ + using namespace ProjectExplorer; using namespace Internal; diff --git a/src/plugins/projectexplorer/projectwizardpage.h b/src/plugins/projectexplorer/projectwizardpage.h index e103544dd2..e653f7ce29 100644 --- a/src/plugins/projectexplorer/projectwizardpage.h +++ b/src/plugins/projectexplorer/projectwizardpage.h @@ -42,6 +42,7 @@ namespace Ui { class WizardPage; } +// Documentation inside. class ProjectWizardPage : public QWizardPage { Q_OBJECT Q_DISABLE_COPY(ProjectWizardPage) diff --git a/src/plugins/projectexplorer/runconfiguration.cpp b/src/plugins/projectexplorer/runconfiguration.cpp index 049b1a2d34..49fbd4e12a 100644 --- a/src/plugins/projectexplorer/runconfiguration.cpp +++ b/src/plugins/projectexplorer/runconfiguration.cpp @@ -151,7 +151,20 @@ IRunConfigurationFactory * findRunConfigurationFactory(RunConfigurationFactoryMa } // namespace -// RunConfiguration +/*! + \class ProjectExplorer::RunConfiguration + \brief Base class for a run configuration. A run configuration specifies how a + target should be run, while the runner (see below) does the actual running. + + Note that all RunControls and the target hold a shared pointer to the RunConfiguration. + That is the lifetime of the RunConfiguration might exceed the life of the target. + The user might still have a RunControl running (or output tab of that RunControl open) + and yet unloaded the target. + + Also, a RunConfiguration might be already removed from the list of RunConfigurations + for a target, but still be runnable via the output tab. +*/ + RunConfiguration::RunConfiguration(Target *target, const QString &id) : ProjectConfiguration(target, id), m_useCppDebugger(true), @@ -184,12 +197,27 @@ void RunConfiguration::addExtraAspects() m_aspects.append(aspect); } +/*! + \brief Used to find out whether a runconfiguration works with the given buildconfiguration. + \note bc may be 0! +*/ + bool RunConfiguration::isEnabled(BuildConfiguration *bc) const { Q_UNUSED(bc); return true; } +/*! + \fn virtual QWidget *ProjectExplorer::RunConfiguration::createConfigurationWidget() + + \brief Returns the widget used to configure this run configuration. Ownership is transferred to the caller +*/ + +/*! + \brief Used to find out whether a runconfiguration works with the active buildconfiguration. +*/ + bool RunConfiguration::isEnabled() const { if (target()->project()->hasActiveBuildSettings() @@ -279,6 +307,22 @@ bool RunConfiguration::fromMap(const QVariantMap &map) return ProjectConfiguration::fromMap(map); } +/*! + \class ProjectExplorer::IRunConfigurationAspect + + \brief Extra configuration aspect. + + Aspects are a mechanism to add RunControl-specific options to a RunConfiguration without + subclassing the RunConfiguration for every addition, preventing a combinatorical explosion + of subclasses or the need to add all options to the base class. +*/ + +/*! + \brief Return extra aspects. + + \sa ProjectExplorer::IRunConfigurationAspect +*/ + QList<IRunConfigurationAspect *> RunConfiguration::extraAspects() const { return m_aspects; @@ -289,6 +333,31 @@ ProjectExplorer::OutputFormatter *RunConfiguration::createOutputFormatter() cons return new OutputFormatter(); } +/*! + \class ProjectExplorer::IRunConfigurationFactory + + \brief Restores RunConfigurations from settings. + + The run configuration factory is used for restoring run configurations from + settings. And used to create new runconfigurations in the "Run Settings" Dialog. + For the first case, bool canRestore(Target *parent, const QString &id) and + RunConfiguration* create(Target *parent, const QString &id) are used. + For the second type, the functions QStringList availableCreationIds(Target *parent) and + QString displayNameForType(const QString&) are used to generate a list of creatable + RunConfigurations, and create(..) is used to create it. +*/ + +/*! + \fn QStringList ProjectExplorer::IRunConfigurationFactory::availableCreationIds(Target *parent) const + + \brief Used to show the list of possible additons to a target, returns a list of types. +*/ + +/*! + \fn QString ProjectExplorer::IRunConfigurationFactory::displayNameForId(const QString &id) const + \brief Used to translate the types to names to display to the user. +*/ + IRunConfigurationFactory::IRunConfigurationFactory(QObject *parent) : QObject(parent) { @@ -316,6 +385,30 @@ IRunConfigurationFactory *IRunConfigurationFactory::restoreFactory(Target *paren return findRunConfigurationFactory(matcher); } +/*! + \class ProjectExplorer::IRunControlFactory + + \brief Creates RunControl objects matching a RunConfiguration +*/ + +/*! + \fn IRunConfigurationAspect *ProjectExplorer::IRunControlFactory::createRunConfigurationAspect() + \brief Return an IRunConfigurationAspect to carry options for RunControls this factory can create. + + If no extra options are required it is allowed to return null like the default implementation does. + This is intended to be called from the RunConfiguration constructor, so passing a RunConfiguration + pointer makes no sense because that object is under construction at the time. +*/ + +/*! + \fn RunConfigWidget *ProjectExplorer::IRunControlFactory::createConfigurationWidget(RunConfiguration *runConfiguration) + + \brief Return a widget used to configure this runner. Ownership is transferred to the caller. + + Return 0 if @p runConfiguration is not suitable for RunControls from this factory, or no user-accessible + configuration is required. +*/ + IRunControlFactory::IRunControlFactory(QObject *parent) : QObject(parent) { @@ -330,6 +423,25 @@ IRunConfigurationAspect *IRunControlFactory::createRunConfigurationAspect() return 0; } +/*! + \class ProjectExplorer::RunControl + \brief Each instance of this class represents one item that is run. +*/ + +/*! + \fn bool ProjectExplorer::RunControl::promptToStop(bool *optionalPrompt = 0) const + + \brief Prompt to stop. If 'optionalPrompt' is passed, a "Do not ask again"- + checkbox will show and the result will be returned in '*optionalPrompt'. +*/ + +/*! + \fn QIcon ProjectExplorer::RunControl::icon() const + \brief Eeturns the icon to be shown in the Outputwindow. + + TODO the icon differs currently only per "mode", so this is more flexible then it needs to be. +*/ + RunControl::RunControl(RunConfiguration *runConfiguration, QString mode) : m_runMode(mode), m_runConfiguration(runConfiguration), m_outputFormatter(0) { @@ -376,7 +488,10 @@ bool RunControl::promptToStop(bool *optionalPrompt) const optionalPrompt); } -// Utility to prompt to terminate application with checkable box. +/*! + \brief Utility to prompt to terminate application with checkable box. +*/ + bool RunControl::showPromptToStopDialog(const QString &title, const QString &text, const QString &stopButtonText, diff --git a/src/plugins/projectexplorer/runconfiguration.h b/src/plugins/projectexplorer/runconfiguration.h index 505966592c..378724c16b 100644 --- a/src/plugins/projectexplorer/runconfiguration.h +++ b/src/plugins/projectexplorer/runconfiguration.h @@ -51,17 +51,7 @@ class OutputFormatter; class RunControl; class Target; -/** - * Base class for a run configuration. A run configuration specifies how a - * target should be run, while the runner (see below) does the actual running. - * - * Note that all RunControls and the target hold a shared pointer to the RunConfiguration. - * That is the lifetime of the RunConfiguration might exceed the life of the target. - * The user might still have a RunControl running (or output tab of that RunControl open) - * and yet unloaded the target. - * Also a RunConfiguration might be already removed from the list of RunConfigurations - * for a target, but stil be runnable via the output tab. - */ +// Documentation inside. class PROJECTEXPLORER_EXPORT RunConfiguration : public ProjectConfiguration { Q_OBJECT @@ -69,20 +59,8 @@ class PROJECTEXPLORER_EXPORT RunConfiguration : public ProjectConfiguration public: virtual ~RunConfiguration(); - /** - * Used to find out whether a runconfiguration works with the given - * buildconfiguration. - * \note bc may be 0! - */ virtual bool isEnabled(BuildConfiguration *bc) const; - - /** - * Used to find out whether a runconfiguration works with the active - * buildconfiguration. - */ bool isEnabled() const; - - /// Returns the widget used to configure this run configuration. Ownership is transferred to the caller virtual QWidget *createConfigurationWidget() = 0; Target *target() const; @@ -99,9 +77,6 @@ public: virtual QVariantMap toMap() const; - // aspects are a mechanism to add RunControl-specific options to a RunConfiguration without - // subclassing the RunConfiguration for every addition, preventing a combinatorical explosion - // of subclasses or the need to add all options to the base class. QList<IRunConfigurationAspect *> extraAspects() const; template <typename T> T *extraAspect() const { @@ -151,15 +126,6 @@ protected: virtual bool fromMap(const QVariantMap &map) = 0; }; -/** - * The run configuration factory is used for restoring run configurations from - * settings. And used to create new runconfigurations in the "Run Settings" Dialog. - * For the first case bool canRestore(Target *parent, const QString &id) and - * RunConfiguration* create(Target *parent, const QString &id) are used. - * For the second type the functions QStringList availableCreationIds(Target *parent) and - * QString displayNameForType(const QString&) are used to generate a list of creatable - * RunConfigurations, and create(..) is used to create it. - */ class PROJECTEXPLORER_EXPORT IRunConfigurationFactory : public QObject { Q_OBJECT @@ -168,10 +134,7 @@ public: explicit IRunConfigurationFactory(QObject *parent = 0); virtual ~IRunConfigurationFactory(); - /// used to show the list of possible additons to a target, returns a list of types virtual QStringList availableCreationIds(Target *parent) const = 0; - - /// used to translate the types to names to display to the user virtual QString displayNameForId(const QString &id) const = 0; virtual bool canCreate(Target *parent, const QString &id) const = 0; @@ -203,15 +166,7 @@ public: virtual QString displayName() const = 0; - /// Return an IRunConfigurationAspect to carry options for RunControls this factory can create. - /// If no extra options are required it is allowed to return null like the default implementation does. - /// This is intended to be called from the RunConfiguration constructor, so passing a RunConfiguration - /// pointer makes no sense because that object is under construction at the time. virtual IRunConfigurationAspect *createRunConfigurationAspect(); - - /// Return a widget used to configure this runner. Ownership is transferred to the caller. - /// If @p runConfiguration is not suitable for RunControls from this factory, or no user-accesible - /// configuration is required, return null. virtual RunConfigWidget *createConfigurationWidget(RunConfiguration *runConfiguration) = 0; }; @@ -230,9 +185,6 @@ signals: void displayNameChanged(const QString &); }; -/** - * Each instance of this class represents one item that is run. - */ class PROJECTEXPLORER_EXPORT RunControl : public QObject { Q_OBJECT @@ -246,15 +198,10 @@ public: virtual ~RunControl(); virtual void start() = 0; - // Prompt to stop. If 'optionalPrompt' is passed, a "Do not ask again"- - // checkbox will show and the result will be returned in '*optionalPrompt'. virtual bool promptToStop(bool *optionalPrompt = 0) const; virtual StopResult stop() = 0; virtual bool isRunning() const = 0; virtual QString displayName() const; - /// \returns the icon to be shown in the outputwindow - // TODO the icon differs currently only per "mode" - // so this is more flexibel then it needs to be virtual QIcon icon() const = 0; bool sameRunConfiguration(const RunControl *other) const; @@ -276,7 +223,6 @@ private slots: void bringApplicationToForegroundInternal(); protected: - // Utility to prompt to terminate application with checkable box. bool showPromptToStopDialog(const QString &title, const QString &text, const QString &stopButtonText = QString(), const QString &cancelButtonText = QString(), diff --git a/src/plugins/projectexplorer/runconfigurationmodel.cpp b/src/plugins/projectexplorer/runconfigurationmodel.cpp index cb65694aae..98256b196b 100644 --- a/src/plugins/projectexplorer/runconfigurationmodel.cpp +++ b/src/plugins/projectexplorer/runconfigurationmodel.cpp @@ -36,9 +36,14 @@ using namespace ProjectExplorer; -/// -/// RunConfigurationsModel -/// +/*! + \class ProjectExplorer::RunConfigurationModel + + \brief A model to represent the run configurations of a target. + + To be used in for the drop down of comboboxes. + Does automatically adjust itself to added and removed RunConfigurations +*/ class RunConfigurationComparer { diff --git a/src/plugins/projectexplorer/runconfigurationmodel.h b/src/plugins/projectexplorer/runconfigurationmodel.h index a2299db1dd..c7ccfeb239 100644 --- a/src/plugins/projectexplorer/runconfigurationmodel.h +++ b/src/plugins/projectexplorer/runconfigurationmodel.h @@ -39,10 +39,7 @@ namespace ProjectExplorer { class Target; class RunConfiguration; -/*! A model to represent the run configurations of a target. - To be used in for the drop down of comboboxes - Does automatically adjust itself to added and removed RunConfigurations -*/ +// Documentation inside. class RunConfigurationModel : public QAbstractListModel { Q_OBJECT diff --git a/src/plugins/projectexplorer/session.cpp b/src/plugins/projectexplorer/session.cpp index c235a2116f..7c96b0f482 100644 --- a/src/plugins/projectexplorer/session.cpp +++ b/src/plugins/projectexplorer/session.cpp @@ -305,7 +305,16 @@ void SessionFile::clearFailedProjectFileNames() m_failedProjects.clear(); } -/* --------------------------------- */ +/*! + \class ProjectExplorer::SessionManager + + \brief Session management. + + TODO the interface of this class is not really great. + The implementation suffers that all the functions from the + public interface just wrap around functions which do the actual work + This could be improved. +*/ SessionManager::SessionManager(QObject *parent) : QObject(parent), @@ -917,6 +926,10 @@ void SessionManager::removeProjects(QList<Project *> remove) setStartupProject(m_file->m_projects.first()); } +/*! + \brief Let other plugins store persistent values within the session file. +*/ + void SessionManager::setValue(const QString &name, const QVariant &value) { if (!m_file) @@ -961,6 +974,10 @@ QString SessionManager::sessionNameToFileName(const QString &session) const return m_core->userResourcePath() + '/' + session + ".qws"; } +/*! + \brief Creates a new default session and switches to it. +*/ + void SessionManager::createAndLoadNewDefaultSession() { emit aboutToLoadSession(); @@ -969,6 +986,10 @@ void SessionManager::createAndLoadNewDefaultSession() emit sessionLoaded(); } +/*! + \brief Just creates a new session (Does not actually create the file). +*/ + bool SessionManager::createSession(const QString &session) { if (sessions().contains(session)) @@ -987,6 +1008,10 @@ bool SessionManager::renameSession(const QString &original, const QString &newNa return deleteSession(original); } +/*! + \brief Deletes session name from session list and file from disk. +*/ + bool SessionManager::deleteSession(const QString &session) { if (!m_sessions.contains(session)) @@ -1013,6 +1038,10 @@ bool SessionManager::cloneSession(const QString &original, const QString &clone) return false; } +/*! + \brief Loads a session, takes a session name (not filename). +*/ + bool SessionManager::loadSession(const QString &session) { // Do nothing if we have that session already loaded, diff --git a/src/plugins/projectexplorer/session.h b/src/plugins/projectexplorer/session.h index 84b8d12d1d..ed73c01370 100644 --- a/src/plugins/projectexplorer/session.h +++ b/src/plugins/projectexplorer/session.h @@ -64,12 +64,6 @@ class SessionFile; class SessionNodeImpl; } // namespace Internal -// TODO the interface of this class is not really great - -// The implementation suffers that all the functions from the -// public interface just wrap around functions which do the actual work - -// This could be improved. class PROJECTEXPLORER_EXPORT SessionManager : public QObject { Q_OBJECT @@ -83,20 +77,14 @@ public: QString lastSession() const; QStringList sessions() const; - // creates a new default session and switches to it void createAndLoadNewDefaultSession(); - - // Just creates a new session (Does not actually create the file) bool createSession(const QString &session); - // delete session name from session list - // delete file from disk bool deleteSession(const QString &session); bool cloneSession(const QString &original, const QString &clone); bool renameSession(const QString &original, const QString &newName); - // loads a session, takes a session name (not filename) bool loadSession(const QString &session); bool save(); diff --git a/src/plugins/projectexplorer/task.cpp b/src/plugins/projectexplorer/task.cpp index 80029fd7ca..56434c8738 100644 --- a/src/plugins/projectexplorer/task.cpp +++ b/src/plugins/projectexplorer/task.cpp @@ -37,6 +37,12 @@ namespace ProjectExplorer unsigned int Task::s_nextId = 1; +/*! + \class ProjectExplorer::Task + \brief Build issue (warning or error). + \sa ProjectExplorer::TaskHub +*/ + Task::Task() : taskId(0), type(Unknown), line(-1) { } diff --git a/src/plugins/projectexplorer/task.h b/src/plugins/projectexplorer/task.h index e20b0090db..1f295a4c4c 100644 --- a/src/plugins/projectexplorer/task.h +++ b/src/plugins/projectexplorer/task.h @@ -41,7 +41,7 @@ namespace ProjectExplorer { -// Build issue (warning or error). +// Documentation inside. class PROJECTEXPLORER_EXPORT Task { public: diff --git a/src/plugins/projectexplorer/toolchain.cpp b/src/plugins/projectexplorer/toolchain.cpp index e683e803da..3531acdf47 100644 --- a/src/plugins/projectexplorer/toolchain.cpp +++ b/src/plugins/projectexplorer/toolchain.cpp @@ -64,8 +64,12 @@ public: } // namespace Internal -// -------------------------------------------------------------------------- -// ToolChain +/*! + \class ProjectExplorer::ToolChain + \brief Representation of a ToolChain. + \sa ProjectExplorer::ToolChainManager +*/ + // -------------------------------------------------------------------------- ToolChain::ToolChain(const QString &id, bool autodetect) : @@ -111,6 +115,12 @@ QString ToolChain::id() const return m_d->m_id; } +/*! + \brief Returns a list of target ids that this tool chain is restricted to. + + An empty list is shows that the toolchain is compatible with all targets. +*/ + QStringList ToolChain::restrictedToTargets() const { return QStringList(); @@ -134,6 +144,12 @@ bool ToolChain::operator == (const ToolChain &tc) const return id() == tc.id(); } +/*! + \brief Used by the toolchainmanager to save user-generated tool chains. + + Make sure to call this method when deriving! +*/ + QVariantMap ToolChain::toMap() const { QVariantMap result; @@ -169,6 +185,12 @@ void ToolChain::setAutoDetected(bool autodetect) toolChainUpdated(); } +/*! + \brief Used by the toolchainmanager to load user-generated tool chains. + + Make sure to call this method when deriving! +*/ + bool ToolChain::fromMap(const QVariantMap &data) { Q_ASSERT(!isAutoDetected()); @@ -178,9 +200,20 @@ bool ToolChain::fromMap(const QVariantMap &data) return true; } -// -------------------------------------------------------------------------- -// ToolChainFactory -// -------------------------------------------------------------------------- +/*! + \class ProjectExplorer::ToolChainFactory + \brief Creates toolchains from settings or autodetects them. +*/ + +/*! + \fn QString ProjectExplorer::ToolChainFactory::displayName() const = 0 + \brief Name used to display the name of the tool chain that will be created. +*/ + +/*! + \fn bool ProjectExplorer::ToolChainFactory::canRestore(const QVariantMap &data) + \brief Used by the ToolChainManager to restore user-generated tool chains. +*/ QList<ToolChain *> ToolChainFactory::autoDetect() { diff --git a/src/plugins/projectexplorer/toolchain.h b/src/plugins/projectexplorer/toolchain.h index a04658c8cc..ed48498eca 100644 --- a/src/plugins/projectexplorer/toolchain.h +++ b/src/plugins/projectexplorer/toolchain.h @@ -57,7 +57,7 @@ class ToolChainFactory; class ToolChainManager; // -------------------------------------------------------------------------- -// ToolChain +// ToolChain (documentation inside) // -------------------------------------------------------------------------- class PROJECTEXPLORER_EXPORT ToolChain @@ -76,8 +76,6 @@ public: virtual bool isValid() const = 0; - /// Returns a list of target ids that this tool chain is restricted to. - /// An empty list is shows that the toolchain is compatible with all targets. virtual QStringList restrictedToTargets() const; virtual QByteArray predefinedMacros() const = 0; @@ -119,16 +117,11 @@ private: friend class ToolChainFactory; }; -// -------------------------------------------------------------------------- -// ToolChainFactory -// -------------------------------------------------------------------------- - class PROJECTEXPLORER_EXPORT ToolChainFactory : public QObject { Q_OBJECT public: - // Name used to display the name of the tool chain that will be created. virtual QString displayName() const = 0; virtual QString id() const = 0; @@ -137,7 +130,6 @@ public: virtual bool canCreate(); virtual ToolChain *create(); - // Used by the ToolChainManager to restore user-generated tool chains virtual bool canRestore(const QVariantMap &data); virtual ToolChain *restore(const QVariantMap &data); diff --git a/src/plugins/projectexplorer/winguiprocess.cpp b/src/plugins/projectexplorer/winguiprocess.cpp index 874d5f61a3..62db7ee5e9 100644 --- a/src/plugins/projectexplorer/winguiprocess.cpp +++ b/src/plugins/projectexplorer/winguiprocess.cpp @@ -40,6 +40,14 @@ using namespace ProjectExplorer::Internal; +/*! + \class ProjectExplorer::Internal::WinGuiProcess + \brief Captures the debug output of a Windows GUI application. + + The output of a Windows GUI application would otherwise not be + visible. Uses the debug interface and emits via a signal. +*/ + WinGuiProcess::WinGuiProcess(QObject *parent) : QThread(parent) { diff --git a/src/plugins/projectexplorer/winguiprocess.h b/src/plugins/projectexplorer/winguiprocess.h index d4f944ec33..c7efe39845 100644 --- a/src/plugins/projectexplorer/winguiprocess.h +++ b/src/plugins/projectexplorer/winguiprocess.h @@ -45,9 +45,7 @@ using namespace Utils; namespace ProjectExplorer { namespace Internal { -/* Captures the debug output of a Windows GUI application (which - * would otherwise not be visible) using the debug interface and - * emits via a signal. */ +// Documentation inside. class WinGuiProcess : public QThread, public AbstractProcess { Q_OBJECT |