Documentation: Add ProjectExplorer plugin..

Reformat existing documentation to qdoc.

doc/api/qtcreator-api.qdoc

@@ -90,6 +90,11 @@
     \o The core plugin. Provides the main window and managers for editors,
     actions, mode windows and files, just to mention the most important ones.
 
+    \row
+    \o \l{ProjectExplorer}
+    \o The project explorer plugin. Provides base classes for
+    project handling.
+
     \row
     \o \l{Find}
     \o Support for searching text in arbitrary widgets, and arbitrary other things.

doc/api/qtcreator-api.qdocconf

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

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

src/plugins/projectexplorer/abi.h

@@ -40,7 +40,7 @@
 namespace ProjectExplorer {
 
 // --------------------------------------------------------------------------
-// ABI
+// ABI (documentation inside)
 // --------------------------------------------------------------------------
 
 class PROJECTEXPLORER_EXPORT Abi

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)

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:

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

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 {

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 {

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

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
 {

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

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

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

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