Merge remote-tracking branch 'origin/4.11'

Change-Id: Iaa3142a7109bc23c2e6ff96d061a58a9c0e31a54

src/libs/aggregation/aggregate.cpp

@@ -30,6 +30,7 @@
 
 /*!
     \namespace Aggregation
+    \inmodule QtCreator
     \brief The Aggregation namespace contains support for bundling related components,
            so that each component exposes the properties and behavior of the
            other components to the outside.
@@ -41,6 +42,7 @@
 
 /*!
     \class Aggregation::Aggregate
+    \inmodule QtCreator
     \ingroup mainclasses
     \threadsafe
 

src/libs/extensionsystem/invoker.cpp

@@ -27,6 +27,45 @@
 
 namespace ExtensionSystem {
 
+/*!
+    \class ExtensionSystem::InvokerBase
+    \internal
+*/
+
+/*!
+    \class ExtensionSystem::Invoker
+    \internal
+*/
+
+/*!
+    \fn Result invoke(QObject *target, const char *slot)
+    Invokes \a slot on \a target by name via Qt's meta method system.
+
+    Returns the result of the meta call.
+*/
+
+/*!
+    \fn Result invoke(QObject *target, const char *slot, const T0 &t0)
+    Invokes \a slot on \a target with argument \a t0 by name via Qt's meta method system.
+
+    Returns the result of the meta call.
+*/
+
+/*!
+    \fn Result invoke(QObject *target, const char *slot, const T0 &t0, const T1 &t1)
+    Invokes \a slot on \a target with arguments \a t0 and \a t1 by name via Qt's meta method system.
+
+    Returns the result of the meta call.
+*/
+
+/*!
+    \fn Result invoke(QObject *target, const char *slot, const T0 &t0, const T1 &t1, const T2 &t2)
+    Invokes \a slot on \a target with arguments \a t0, \a t1 and \a t2 by name
+    via Qt's meta method system.
+
+    Returns the result of the meta call.
+*/
+
 InvokerBase::InvokerBase()
 {
     lastArg = 0;

src/libs/extensionsystem/invoker.h

@@ -150,6 +150,7 @@ public:
     }
 };
 
+#ifndef Q_QDOC
 template <class Result>
 Result invokeHelper(InvokerBase &in, QObject *target, const char *slot)
 {
@@ -164,6 +165,7 @@ inline void invokeHelper<void>(InvokerBase &in, QObject *target, const char *slo
 {
     in.invoke(target, slot);
 }
+#endif
 
 template<class Result>
 Result invoke(QObject *target, const char *slot)

src/libs/extensionsystem/iplugin.cpp

@@ -30,47 +30,22 @@
 
 /*!
     \class ExtensionSystem::IPlugin
+    \inmodule QtCreator
     \ingroup mainclasses
-    \brief The IPlugin class is the base class for all plugins.
-
-    The IPlugin class is an abstract class that must be implemented
+    \brief The IPlugin class is an abstract base class that must be implemented
     once for each plugin.
-    A plugin consists of two parts: a description file, and a library
-    that at least contains the IPlugin implementation.
 
-    \section1 Plugin Specification
+    A plugin needs to provide meta data in addition to the actual plugin
+    library, so the plugin manager can find the plugin, resolve its
+    dependencies, and load it. For more information, see \l{Plugin Meta Data}.
 
-    A plugin needs to provide a plugin specification file in addition
-    to the actual plugin library, so the plugin manager can find the plugin,
-    resolve its dependencies, and load it. For more information,
-    see \l{Plugin Meta Data}.
-
-    \section1 Plugin Implementation
     Plugins must provide one implementation of the IPlugin class, located
     in a library that matches the \c name attribute given in their
-    XML description. The IPlugin implementation must be exported and
+    meta data. The IPlugin implementation must be exported and
     made known to Qt's plugin system, using the \c Q_PLUGIN_METADATA macro with
     an IID set to \c "org.qt-project.Qt.QtCreatorPlugin".
 
-
-    After the plugins' XML files have been read, and dependencies have been
-    found, the plugin loading is done in three phases:
-    \list 1
-    \li All plugin libraries are loaded in \e{root-to-leaf} order of the
-       dependency tree.
-    \li All plugins' initialize functions are called in \e{root-to-leaf} order
-       of the dependency tree. This is a good time to create objects
-       needed by other plugins and register them via appropriate core functions
-       or, if a weak dependency is neceessary to be implemented, to put
-       them into the global object pool.
-    \li All plugins' extensionsInitialized() functions are called in \e{leaf-to-root}
-       order of the dependency tree. At this point, plugins can
-       be sure that all plugins that depend on this plugin have
-       been initialized completely and objects these plugins wish to
-       share have been registered or are available in the global object pool.
-    \endlist
-    If library loading or initialization of a plugin fails, all plugins
-    that depend on that plugin also fail.
+    For more information, see \l{Plugin Life Cycle}.
 */
 
 /*!
@@ -183,8 +158,6 @@
 
     Returns a QObject that blocks the command until it is destroyed, if \c -block
     is used.
-
-    \sa PluginManager::serializedArguments()
 */
 
 /*!

src/libs/extensionsystem/plugindetailsview.cpp

@@ -38,6 +38,7 @@
 
 /*!
     \class ExtensionSystem::PluginDetailsView
+    \inmodule QtCreator
     \brief The PluginDetailsView class implements a widget that displays the
     contents of a PluginSpec.
 

src/libs/extensionsystem/pluginerroroverview.cpp

@@ -32,6 +32,11 @@ Q_DECLARE_METATYPE(ExtensionSystem::PluginSpec*)
 
 namespace ExtensionSystem {
 
+/*!
+    \class ExtensionSystem::PluginErrorOverview
+    \internal
+*/
+
 PluginErrorOverview::PluginErrorOverview(QWidget *parent) :
     QDialog(parent),
     m_ui(new Internal::Ui::PluginErrorOverview)

src/libs/extensionsystem/pluginerrorview.cpp

@@ -31,6 +31,7 @@
 
 /*!
     \class ExtensionSystem::PluginErrorView
+    \inmodule QtCreator
     \brief The PluginErrorView class implements a widget that displays the
     state and error message of a PluginSpec.
 

src/libs/extensionsystem/pluginmanager.cpp

@@ -75,6 +75,7 @@ enum { debugLeaks = 0 };
 
 /*!
     \namespace ExtensionSystem
+    \inmodule QtCreator
     \brief The ExtensionSystem namespace provides classes that belong to the
            core plugin system.
 
@@ -89,6 +90,7 @@ enum { debugLeaks = 0 };
 
 /*!
     \class ExtensionSystem::PluginManager
+    \inmodule QtCreator
     \ingroup mainclasses
 
     \brief The PluginManager class implements the core plugin system that

src/libs/extensionsystem/pluginspec.cpp

@@ -48,6 +48,7 @@
 
 /*!
     \class ExtensionSystem::PluginDependency
+    \inmodule QtCreator
     \brief The PluginDependency class contains the name and required compatible
     version number of a plugin's dependency.
 
@@ -91,6 +92,7 @@
 
 /*!
     \class ExtensionSystem::PluginSpec
+    \inmodule QtCreator
     \brief The PluginSpec class contains the information of the plugin's embedded meta data
     and information about the plugin's current state.
 
@@ -131,10 +133,20 @@
             The plugin instance has been deleted.
 */
 
+/*!
+    \class ExtensionSystem::PluginArgumentDescription
+    \inmodule QtCreator
+    \brief The PluginArgumentDescriptions class holds a list of descriptions of
+    command line arguments that a plugin processes.
+
+    \sa PluginSpec::argumentDescriptions()
+*/
+
 using namespace ExtensionSystem;
 using namespace ExtensionSystem::Internal;
 
 /*!
+    \fn uint ExtensionSystem::qHash(const ExtensionSystem::PluginDependency &value)
     \internal
 */
 uint ExtensionSystem::qHash(const PluginDependency &value)
@@ -163,6 +175,9 @@ static QString typeString(PluginDependency::Type type)
     }
 }
 
+/*!
+    \internal
+*/
 QString PluginDependency::toString() const
 {
     return name + " (" + version + typeString(type) + ")";
@@ -186,7 +201,8 @@ PluginSpec::~PluginSpec()
 }
 
 /*!
-    The plugin name. This is valid after the PluginSpec::Read state is reached.
+    Returns the plugin name. This is valid after the PluginSpec::Read state is
+    reached.
 */
 QString PluginSpec::name() const
 {
@@ -194,7 +210,8 @@ QString PluginSpec::name() const
 }
 
 /*!
-    The plugin version. This is valid after the PluginSpec::Read state is reached.
+    Returns the plugin version. This is valid after the PluginSpec::Read state
+    is reached.
 */
 QString PluginSpec::version() const
 {
@@ -202,7 +219,8 @@ QString PluginSpec::version() const
 }
 
 /*!
-    The plugin compatibility version. This is valid after the PluginSpec::Read state is reached.
+    Returns the plugin compatibility version. This is valid after the
+    PluginSpec::Read state is reached.
 */
 QString PluginSpec::compatVersion() const
 {
@@ -210,7 +228,8 @@ QString PluginSpec::compatVersion() const
 }
 
 /*!
-    The plugin vendor. This is valid after the PluginSpec::Read state is reached.
+    Returns the plugin vendor. This is valid after the PluginSpec::Read
+    state is reached.
 */
 QString PluginSpec::vendor() const
 {
@@ -218,7 +237,8 @@ QString PluginSpec::vendor() const
 }
 
 /*!
-    The plugin copyright. This is valid after the PluginSpec::Read state is reached.
+    Returns the plugin copyright. This is valid after the PluginSpec::Read
+     state is reached.
 */
 QString PluginSpec::copyright() const
 {
@@ -226,7 +246,8 @@ QString PluginSpec::copyright() const
 }
 
 /*!
-    The plugin license. This is valid after the PluginSpec::Read state is reached.
+    Returns the plugin license. This is valid after the PluginSpec::Read
+    state is reached.
 */
 QString PluginSpec::license() const
 {
@@ -234,7 +255,8 @@ QString PluginSpec::license() const
 }
 
 /*!
-    The plugin description. This is valid after the PluginSpec::Read state is reached.
+    Returns the plugin description. This is valid after the PluginSpec::Read
+    state is reached.
 */
 QString PluginSpec::description() const
 {
@@ -242,7 +264,7 @@ QString PluginSpec::description() const
 }
 
 /*!
-    The plugin URL where you can find more information about the plugin.
+    Returns the plugin URL where you can find more information about the plugin.
     This is valid after the PluginSpec::Read state is reached.
 */
 QString PluginSpec::url() const
@@ -251,7 +273,8 @@ QString PluginSpec::url() const
 }
 
 /*!
-    The category that the plugin belongs to. Categories are groups of plugins which allow for keeping them together in the UI.
+    Returns the category that the plugin belongs to. Categories are used to
+    group plugins together in the UI.
     Returns an empty string if the plugin does not belong to a category.
 */
 QString PluginSpec::category() const
@@ -260,7 +283,8 @@ QString PluginSpec::category() const
 }
 
 /*!
-    A QRegExp matching the platforms this plugin works on. An empty pattern implies all platforms.
+    Returns a QRegExp matching the platforms this plugin works on. An empty
+    pattern implies all platforms.
     \since 3.0
 */
 
@@ -269,17 +293,26 @@ QRegExp PluginSpec::platformSpecification() const
     return d->platformSpecification;
 }
 
+/*!
+    Returns whether the plugin works on the host platform.
+*/
 bool PluginSpec::isAvailableForHostPlatform() const
 {
     return d->platformSpecification.isEmpty()
             || d->platformSpecification.indexIn(PluginManager::platformName()) >= 0;
 }
 
+/*!
+    Returns whether the plugin is required.
+*/
 bool PluginSpec::isRequired() const
 {
     return d->required;
 }
 
+/*!
+    Returns whether the plugin is hidden by default.
+*/
 bool PluginSpec::isHiddenByDefault() const
 {
     return d->hiddenByDefault;
@@ -296,7 +329,7 @@ bool PluginSpec::isExperimental() const
 /*!
     Returns whether the plugin is enabled by default.
     A plugin might be disabled because the plugin is experimental, or because
-    the install settings define it as disabled by default.
+    the installation settings define it as disabled by default.
 */
 bool PluginSpec::isEnabledByDefault() const
 {
@@ -307,9 +340,10 @@ bool PluginSpec::isEnabledByDefault() const
     Returns whether the plugin should be loaded at startup,
     taking into account the default enabled state, and the user's settings.
 
-    \note This function might return false even if the plugin is loaded as a requirement of another
-    enabled plugin.
-    \sa PluginSpec::isEffectivelyEnabled
+    \note This function might return \c false even if the plugin is loaded
+    as a requirement of another enabled plugin.
+
+    \sa isEffectivelyEnabled()
 */
 bool PluginSpec::isEnabledBySettings() const
 {
@@ -318,7 +352,7 @@ bool PluginSpec::isEnabledBySettings() const
 
 /*!
     Returns whether the plugin is loaded at startup.
-    \see PluginSpec::isEnabledBySettings
+    \sa isEnabledBySettings()
 */
 bool PluginSpec::isEffectivelyEnabled() const
 {
@@ -332,7 +366,8 @@ bool PluginSpec::isEffectivelyEnabled() const
 }
 
 /*!
-    Returns true if loading was not done due to user unselecting this plugin or its dependencies.
+    Returns \c true if loading was not done due to user unselecting this
+    plugin or its dependencies.
 */
 bool PluginSpec::isEnabledIndirectly() const
 {
@@ -340,7 +375,8 @@ bool PluginSpec::isEnabledIndirectly() const
 }
 
 /*!
-    Returns whether the plugin is enabled via the -load option on the command line.
+    Returns whether the plugin is enabled via the \c -load option on the
+    command line.
 */
 bool PluginSpec::isForceEnabled() const
 {
@@ -348,7 +384,8 @@ bool PluginSpec::isForceEnabled() const
 }
 
 /*!
-    Returns whether the plugin is disabled via the -noload option on the command line.
+    Returns whether the plugin is disabled via the \c -noload option on the
+     command line.
 */
 bool PluginSpec::isForceDisabled() const
 {
@@ -363,6 +400,9 @@ QVector<PluginDependency> PluginSpec::dependencies() const
     return d->dependencies;
 }
 
+/*!
+    Returns the plugin meta data.
+*/
 QJsonObject PluginSpec::metaData() const
 {
     return d->metaData;
@@ -378,8 +418,7 @@ PluginSpec::PluginArgumentDescriptions PluginSpec::argumentDescriptions() const
 }
 
 /*!
-    The absolute path to the directory containing the plugin XML description file
-    this PluginSpec corresponds to.
+    Returns the absolute path to the directory containing the plugin.
 */
 QString PluginSpec::location() const
 {
@@ -387,8 +426,7 @@ QString PluginSpec::location() const
 }
 
 /*!
-    The absolute path to the plugin XML description file (including the file name)
-    this PluginSpec corresponds to.
+    Returns the absolute path to the plugin.
 */
 QString PluginSpec::filePath() const
 {
@@ -396,7 +434,7 @@ QString PluginSpec::filePath() const
 }
 
 /*!
-    Command line arguments specific to the plugin. Set at startup.
+    Returns command line arguments specific to the plugin. Set at startup.
 */
 
 QStringList PluginSpec::arguments() const
@@ -424,7 +462,7 @@ void PluginSpec::addArgument(const QString &argument)
 
 
 /*!
-    The state in which the plugin currently is.
+    Returns the state in which the plugin currently is.
     See the description of the PluginSpec::State enum for details.
 */
 PluginSpec::State PluginSpec::state() const
@@ -433,7 +471,7 @@ PluginSpec::State PluginSpec::state() const
 }
 
 /*!
-    Returns whether an error occurred while reading/starting the plugin.
+    Returns whether an error occurred while reading or starting the plugin.
 */
 bool PluginSpec::hasError() const
 {
@@ -441,7 +479,8 @@ bool PluginSpec::hasError() const
 }
 
 /*!
-    Detailed, possibly multi-line, error description in case of an error.
+    Returns a detailed, possibly multi-line, error description in case of an
+    error.
 */
 QString PluginSpec::errorString() const
 {
@@ -460,8 +499,9 @@ bool PluginSpec::provides(const QString &pluginName, const QString &version) con
 }
 
 /*!
-    The corresponding IPlugin instance, if the plugin library has already been successfully loaded,
-    i.e. the PluginSpec::Loaded state is reached.
+    Returns the corresponding IPlugin instance, if the plugin library has
+    already been successfully loaded. That is, the PluginSpec::Loaded state
+    is reached.
 */
 IPlugin *PluginSpec::plugin() const
 {
@@ -479,6 +519,10 @@ QHash<PluginDependency, PluginSpec *> PluginSpec::dependencySpecs() const
     return d->dependencySpecs;
 }
 
+/*!
+    Returns whether the plugin requires any of the plugins specified by
+    \a plugins.
+*/
 bool PluginSpec::requiresAny(const QSet<PluginSpec *> &plugins) const
 {
     return Utils::anyOf(d->dependencySpecs.keys(), [this, &plugins](const PluginDependency &dep) {
@@ -487,6 +531,11 @@ bool PluginSpec::requiresAny(const QSet<PluginSpec *> &plugins) const
     });
 }
 
+/*!
+    Sets whether the plugin should be loaded at startup to \a value.
+
+    \sa isEnabledBySettings()
+*/
 void PluginSpec::setEnabledBySettings(bool value)
 {
     d->setEnabledBySettings(value);

src/libs/extensionsystem/pluginview.cpp

@@ -44,6 +44,7 @@
 
 /*!
     \class ExtensionSystem::PluginView
+    \inmodule QtCreator
     \brief The PluginView class implements a widget that shows a list of all
     plugins and their state.
 
@@ -67,6 +68,11 @@
     for example by a double-click.
 */
 
+/*!
+    \fn void PluginView::pluginSettingsChanged(ExtensionSystem::PluginSpec *spec)
+    The settings for the plugin list entry corresponding to \a spec changed.
+*/
+
 Q_DECLARE_METATYPE(ExtensionSystem::PluginSpec*)
 
 using namespace Utils;
@@ -321,8 +327,8 @@ private:
 using namespace ExtensionSystem::Internal;
 
 /*!
-    Constructs a PluginView that gets the list of plugins from the
-    given plugin \a manager with a given \a parent widget.
+    Constructs a plugin view with \a parent that displays a list of plugins
+    from a plugin manager.
 */
 PluginView::PluginView(QWidget *parent)
     : QWidget(parent)
@@ -383,18 +389,27 @@ PluginSpec *PluginView::currentPlugin() const
     return pluginForIndex(m_categoryView->currentIndex());
 }
 
+/*!
+    Sets the \a filter for listing plugins.
+*/
 void PluginView::setFilter(const QString &filter)
 {
     m_sortModel->setFilterFixedString(filter);
     m_categoryView->expandAll();
 }
 
+/*!
+    Sets the list filtering to \a showHidden.
+*/
 void PluginView::setShowHidden(bool showHidden)
 {
     m_sortModel->setShowHidden(showHidden);
     m_categoryView->expandAll();
 }
 
+/*!
+    Returns whether hidden plugins are listed.
+*/
 bool PluginView::isShowingHidden() const
 {
     return m_sortModel->isShowingHidden();

src/libs/utils/qrcparser.cpp

@@ -170,7 +170,7 @@ QrcParser::QrcParser()
 }
 
 /*!
-    Destructs the QRC parser.
+    \internal
 */
 QrcParser::~QrcParser()
 {
@@ -178,7 +178,12 @@ QrcParser::~QrcParser()
 }
 
 /*!
-    Returns the \a contents of the file at \a path.
+    Parses the QRC file at \a path. If \a contents is not empty, it is used as
+    the file contents instead of reading it from the file system.
+
+    Returns whether the parsing succeeded.
+
+    \sa errorMessages(), parseQrcFile()
 */
 bool QrcParser::parseFile(const QString &path, const QString &contents)
 {
@@ -304,7 +309,13 @@ QrcCache::~QrcCache()
 }
 
 /*!
-    Returns the \a contents of a file at \a path.
+    Parses the QRC file at \a path and caches the parser. If \a contents is not
+    empty, it is used as the file contents instead of reading it from the file
+    system.
+
+    Returns whether the parsing succeeded.
+
+    \sa QrcParser::errorMessages(), QrcParser::parseQrcFile()
 */
 QrcParser::ConstPtr QrcCache::addPath(const QString &path, const QString &contents)
 {
@@ -320,7 +331,7 @@ void QrcCache::removePath(const QString &path)
 }
 
 /*!
-    Returns updates to the \a contents of a file at \a path.
+    Reparses the QRC file at \a path and returns the \a contents of the file.
 */
 QrcParser::ConstPtr QrcCache::updatePath(const QString &path, const QString &contents)
 {
@@ -328,7 +339,7 @@ QrcParser::ConstPtr QrcCache::updatePath(const QString &path, const QString &con
 }
 
 /*!
-    Returns the parsed \a path.
+    Returns the cached QRC parser for the QRC file at \a path.
 */
 QrcParser::ConstPtr QrcCache::parsedPath(const QString &path)
 {