Commit 0479abdc authored by Tobias Hunger's avatar Tobias Hunger

QDoc: Fix QDoc warnings

This patch fixes ~1100 warnings from qdoc

Change-Id: Ia9555db675acbf8083b2f87d9855a62a3a34ccb9
Reviewed-by: default avatarLeena Miettinen <riitta-leena.miettinen@digia.com>
parent 529cc963
This diff is collapsed.
This diff is collapsed.
......@@ -44,22 +44,22 @@
\section1 Basics
\list
\o \l{Getting and Building Qt Creator}
\o \l{Creating Your First Plugin}
\o \l{Plugin Specifications}
\o \l{Plugin Life Cycle}
\li \l{Getting and Building Qt Creator}
\li \l{Creating Your First Plugin}
\li \l{Plugin Specifications}
\li \l{Plugin Life Cycle}
\endlist
\section1 Design Principles
\list
\o \l{The Plugin Manager, the Object Pool, and Registered Objects}
\o \l{Aggregations}
\o \l{Extending and Providing Interfaces}
\li \l{The Plugin Manager, the Object Pool, and Registered Objects}
\li \l{Aggregations}
\li \l{Extending and Providing Interfaces}
\endlist
\section1 Creating 3rd-Party Plugins
\list
\o \l{A Note on Binary Compatibility}
\o \l{Creating User-Installable Plugins}
\li \l{A Note on Binary Compatibility}
\li \l{Creating User-Installable Plugins}
\endlist
*/
......@@ -49,20 +49,20 @@
\table
\header
\o Tag
\o Meaning
\li Tag
\li Meaning
\row
\o externaltool
\o Root element in the XML file that specifies an external tool.
\li externaltool
\li Root element in the XML file that specifies an external tool.
\endtable
\table
\header
\o Attribute
\o Meaning
\li Attribute
\li Meaning
\row
\o id
\o A string that identifies the external tool.
Two tools cannot have the same id. Required.
\li id
\li A string that identifies the external tool.
Two tools cannot have the same id. Required.
\endtable
\section2 Description Tags
......@@ -74,30 +74,30 @@
\table
\header
\o Tag
\o Meaning
\li Tag
\li Meaning
\row
\o description
\o Short, one-line description of what the tool is for. Required.
\li description
\li Short, one-line description of what the tool is for. Required.
\row
\o displayname
\o Name to show in the menu item for the tool. Required.
\li displayname
\li Name to show in the menu item for the tool. Required.
\row
\o category
\o Name of the category to show the tool in.
This is the name of the sub menu of the \c { Tools > External }
menu where the tool is placed. For example, specify the value
\c "Text" to display the tool in the \c { Tools > External > Text }
menu. Required.
\li category
\li Name of the category to show the tool in.
This is the name of the sub menu of the \c { Tools > External }
menu where the tool is placed. For example, specify the value
\c "Text" to display the tool in the \c { Tools > External > Text }
menu. Required.
\endtable
\table
\header
\o Attribute
\o Meaning
\li Attribute
\li Meaning
\row
\o xml:lang
\o Language code (such as, \c "en" or \c "de") of the language that is used for
the description, display name, or category. Optional.
\li xml:lang
\li Language code (such as, \c "en" or \c "de") of the language that is used for
the description, display name, or category. Optional.
\endtable
\section2 Executable Specification Tag
......@@ -107,32 +107,32 @@
\table
\header
\o Tag
\o Meaning
\li Tag
\li Meaning
\row
\o executable
\o Encloses subtags that specify what to run and which parameters to use. Required.
\li executable
\li Encloses subtags that specify what to run and which parameters to use. Required.
\endtable
\table
\header
\o Attribute
\o Meaning
\li Attribute
\li Meaning
\row
\o output
\o Specifies how to handle the tool's standard output stream.
\li output
\li Specifies how to handle the tool's standard output stream.
Defaults to \c ShowInPane. Optional.
\row
\o error
\o Specifies how to handle the tool's standard error stream.
Defaults to \c ShowInPane. Optional.
\li error
\li Specifies how to handle the tool's standard error stream.
Defaults to \c ShowInPane. Optional.
\row
\o modifiesdocument
\o Specifies whether Qt Creator should expect changes to the current
document. If this flag is set, Qt Creator prompts users to save
changes to the current document before running the tool,
and silently reloads the current document after the tool has finished.
Possible values are: \c "yes" or \c "no" (defaults to \c "no").
Optional.
\li modifiesdocument
\li Specifies whether Qt Creator should expect changes to the current
document. If this flag is set, Qt Creator prompts users to save
changes to the current document before running the tool,
and silently reloads the current document after the tool has finished.
Possible values are: \c "yes" or \c "no" (defaults to \c "no").
Optional.
\endtable
The \c executable tag allows the following subtags. You must specify at least
......@@ -140,28 +140,28 @@
\table
\header
\o Subtag
\o Meaning
\li Subtag
\li Meaning
\row
\o path
\o File path to the executable to run, including filename. If you
specify the executable name without a path, Qt creator checks the
system PATH environment variable for a path to the executable. You
can specify the path multiple times. Qt Creator tries to resolve the
references in the given order and runs the first executable that it
finds. Required.
\li path
\li File path to the executable to run, including filename. If you
specify the executable name without a path, Qt creator checks the
system PATH environment variable for a path to the executable. You
can specify the path multiple times. Qt Creator tries to resolve the
references in the given order and runs the first executable that it
finds. Required.
\row
\o arguments
\o Command line arguments for the executable. Specify the string in the
same format (with respect to quoting and argument splitting, for
example) as you would specify it on the command line of the platform
the tool runs on. Optional.
\li arguments
\li Command line arguments for the executable. Specify the string in the
same format (with respect to quoting and argument splitting, for
example) as you would specify it on the command line of the platform
the tool runs on. Optional.
\row
\o workingdirectory
\o The working directory for the executable. Optional.
\li workingdirectory
\li The working directory for the executable. Optional.
\row
\o input
\o A potentially multiline string that is passed to the tool via standard input stream.
\li input
\li A potentially multiline string that is passed to the tool via standard input stream.
\endtable
\section1 Example
......
......@@ -36,81 +36,81 @@
your plugin with.
\list 1
\o Select \gui{File > New File or Project > Libraries > Qt Creator Plugin > Choose}.
\li Select \gui{File > New File or Project > Libraries > Qt Creator Plugin > Choose}.
\image firstplugin-wizard.png "Choose the \QC Plugin Wizard"
\image firstplugin-wizard.png "Choose the \QC Plugin Wizard"
The \gui{Introduction and Project Location} dialog opens.
The \gui{Introduction and Project Location} dialog opens.
\image firstplugin-nameandpath.png "Choose Name and Place of the Project"
\image firstplugin-nameandpath.png "Choose Name and Place of the Project"
\o Give your project a name and specify in which path
this project will be created. The actual plugin's name can be different
from the project name. You will choose that name later in the wizard.
Continue to the next page.
\li Give your project a name and specify in which path
this project will be created. The actual plugin's name can be different
from the project name. You will choose that name later in the wizard.
Continue to the next page.
The \gui{Kit Selection} dialog opens.
The \gui{Kit Selection} dialog opens.
\image firstplugin-kitselection.png "Choose the kit to build and run your project with"
\image firstplugin-kitselection.png "Choose the kit to build and run your project with"
\o Select the \l{glossary-buildandrun-kit}{kit} to build and run your project with.
For a \QC plugin this needs to be a kit with \gui{Desktop} device type,
and a Qt version that is compatible with the Qt version that your
\QC was built with (in the best case the exact same build).
If you use an incompatible Qt version to build your plugin, you
will get errors while \QC tries to load your plugin.
Continue to the next page.
\li Select the \l{glossary-buildandrun-kit}{kit} to build and run your project with.
For a \QC plugin this needs to be a kit with \gui{Desktop} device type,
and a Qt version that is compatible with the Qt version that your
\QC was built with (in the best case the exact same build).
If you use an incompatible Qt version to build your plugin, you
will get errors while \QC tries to load your plugin.
Continue to the next page.
The \gui{Plugin Information} dialog opens.
The \gui{Plugin Information} dialog opens.
\image firstplugin-pluginsetup.png "Specify Your Plugin Details"
\image firstplugin-pluginsetup.png "Specify Your Plugin Details"
\o In the \gui{Plugin name} field, type \gui{Example}. The name of the plugin
is used as its identifier, and also is the base for the file names and
classes in the code.
\li In the \gui{Plugin name} field, type \gui{Example}. The name of the plugin
is used as its identifier, and also is the base for the file names and
classes in the code.
\o The values of the following fields are mainly informational, and
are shown in the detailed view in \QC's plugin overview
(\gui{Help > About Plugins}, or \gui{Qt Creator > About Plugins}
on Mac).
\li The values of the following fields are mainly informational, and
are shown in the detailed view in \QC's plugin overview
(\gui{Help > About Plugins}, or \gui{Qt Creator > About Plugins}
on Mac).
\list
\o \gui{Vendor name} is a short one-word name of the company
or organization that created the plugin. This is also used for
the path name where the plugin will be deployed to.
\o \gui{Copyright} is a one-line, short copyright string.
\o \gui{License} is a multi-line license text (but shouldn't be pages over pages long,
since the interface doesn't allow nice reading of long texts).
\o \gui{Description} is a relatively short, but
possibly multi-line description of what the plugin does.
\o \gui{URL} is a website where the user can find more
information about the plugin and/or organization providing it.
\list
\li \gui{Vendor name} is a short one-word name of the company
or organization that created the plugin. This is also used for
the path name where the plugin will be deployed to.
\li \gui{Copyright} is a one-line, short copyright string.
\li \gui{License} is a multi-line license text (but shouldn't be pages over pages long,
since the interface doesn't allow nice reading of long texts).
\li \gui{Description} is a relatively short, but
possibly multi-line description of what the plugin does.
\li \gui{URL} is a website where the user can find more
information about the plugin and/or organization providing it.
\endlist
\o Set the \gui{Qt Creator sources} and \gui{Qt Creator build} fields to
the source and build directory of the \QC
instance you want to use to test your plugin with, respectively.
If you don't do that correctly you will get compile errors for your
plugin, and your plugin might not show up in \QC at all.
\o In the \gui{Deploy into} list, select \gui{Qt Creator build}. This sets
your .pro file up to deploy your plugin directly into your \QC build's
plugin directory (requires you to have write permissions there).
The other option, \gui{Local user settings}, sets your .pro file up to
deploy your plugin into \QC's user plugin path
(for example \c{~/.config/QtProject/qtcreator/plugins} on Unix systems).
We choose \gui{Qt Creator build} because we use a self-compiled
\QC, and want the plugin to be only loaded by that \QC
instance.
Continue to the next page.
The \gui{Project Management} dialog opens.
\image firstplugin-summary.png "Summary of Created Files"
\o Review the files that will be created, choose a version control
system that \QC should use for your project (always a good idea!),
and finish the wizard.
\li Set the \gui{Qt Creator sources} and \gui{Qt Creator build} fields to
the source and build directory of the \QC
instance you want to use to test your plugin with, respectively.
If you don't do that correctly you will get compile errors for your
plugin, and your plugin might not show up in \QC at all.
\li In the \gui{Deploy into} list, select \gui{Qt Creator build}. This sets
your .pro file up to deploy your plugin directly into your \QC build's
plugin directory (requires you to have write permissions there).
The other option, \gui{Local user settings}, sets your .pro file up to
deploy your plugin into \QC's user plugin path
(for example \c{~/.config/QtProject/qtcreator/plugins} on Unix systems).
We choose \gui{Qt Creator build} because we use a self-compiled
\QC, and want the plugin to be only loaded by that \QC
instance.
Continue to the next page.
The \gui{Project Management} dialog opens.
\image firstplugin-summary.png "Summary of Created Files"
\li Review the files that will be created, choose a version control
system that \QC should use for your project (always a good idea!),
and finish the wizard.
\endlist
\section1 Building and Running the Plugin
......@@ -138,26 +138,26 @@
\table
\header
\o File
\o Role
\li File
\li Role
\row
\o \c{Example.pluginspec.in}
\o Template plugin specification. QMake creates a \c{Example.pluginspec}
from this file, which is read by \QC to find out about the plugin.
\li \c{Example.pluginspec.in}
\li Template plugin specification. QMake creates a \c{Example.pluginspec}
from this file, which is read by \QC to find out about the plugin.
\row
\o \c{example.pro}
\o Project file, used by QMake to generate a Makefile that then is used to
build the plugin.
\li \c{example.pro}
\li Project file, used by QMake to generate a Makefile that then is used to
build the plugin.
\row
\o \c{example_global.h}
\o Contains macro definitions that are useful when this plugin should export
symbols to other plugins.
\li \c{example_global.h}
\li Contains macro definitions that are useful when this plugin should export
symbols to other plugins.
\row
\o \c{exampleconstants.h}
\o Header defining constants used by the plugin code.
\li \c{exampleconstants.h}
\li Header defining constants used by the plugin code.
\row
\o \c{exampleplugin.h/.cpp}
\o C++ header and source files that define the plugin class that will be
\li \c{exampleplugin.h/.cpp}
\li C++ header and source files that define the plugin class that will be
instanciated and run by \QC's plugin manager.
\endtable
......
......@@ -27,69 +27,69 @@
When you start \QC, the plugin manager does the following:
\list 1
\o Looks in its search paths for
all .pluginspec files, and reads them. This is the first point where
loading a plugin can fail in the worst case of a malformed plugin spec.
\o Creates an instance of the \l{ExtensionSystem::PluginSpec} class for
each plugin. This class is a container for
all the information from the plugin specification, and additionally
tracks the state of the plugin.
You can get the \l{ExtensionSystem::PluginSpec} instances via the
plugin manager's \l{ExtensionSystem::PluginManager::plugins()}{plugins()}
method, or, after a plugin is loaded, through the plugin's
\l{ExtensionSystem::IPlugin::pluginSpec()}{pluginSpec()} method.
\o Sets the plugins to \c Read state.
\o Verifies that the dependencies of each plugin
exist and are compatible. For more information about plugin dependencies,
see \l{Plugin Specifications}.
\o Sets the plugins to \c Resolved state.
\o Sorts all plugins into a list that we call the \e{load queue}, where the
dependencies of a plugin are positioned after the plugin
(but not necessarily \e directly after the plugin).
It will make sure that we load
and initialize the plugins in proper order.
\o Loads the plugins' libraries, and creates their IPlugin instances
in the order of the load queue. At this point the
plugin constructors are called. Plugins that other plugins depend on
are created first.
\o Sets the plugins to \c Loaded state.
\o Calls the \l{ExtensionSystem::IPlugin::initialize()}{initialize()} methods of
all plugins in the order of the load queue. In the \c initialize method,
a plugin should make sure that all exported interfaces are set up and available
to other plugins. A plugin can assume that plugins they depend on have set up
their exported interfaces. For example, the \c Core plugin sets up the
\l{Core::ActionManager}, \l{Core::EditorManager} and all other publicly available
interfaces, so other plugins can request and use them.
The \l{ExtensionSystem::IPlugin::initialize()}{initialize()} method of a plugin
is a good place for
\list
\o registering objects in the plugin manager's object pool
(see \l{The Plugin Manager, the Object Pool, and Registered Objects})
\o loading settings
\o adding new menus, and new actions to menus
\o connecting to other plugin's signals.
\li Looks in its search paths for
all .pluginspec files, and reads them. This is the first point where
loading a plugin can fail in the worst case of a malformed plugin spec.
\li Creates an instance of the \l{ExtensionSystem::PluginSpec} class for
each plugin. This class is a container for
all the information from the plugin specification, and additionally
tracks the state of the plugin.
You can get the \l{ExtensionSystem::PluginSpec} instances via the
plugin manager's \l{ExtensionSystem::PluginManager::plugins()}{plugins()}
method, or, after a plugin is loaded, through the plugin's
\l{ExtensionSystem::IPlugin::pluginSpec()}{pluginSpec()} method.
\li Sets the plugins to \c Read state.
\li Verifies that the dependencies of each plugin
exist and are compatible. For more information about plugin dependencies,
see \l{Plugin Specifications}.
\li Sets the plugins to \c Resolved state.
\li Sorts all plugins into a list that we call the \e{load queue}, where the
dependencies of a plugin are positioned after the plugin
(but not necessarily \e directly after the plugin).
It will make sure that we load
and initialize the plugins in proper order.
\li Loads the plugins' libraries, and creates their IPlugin instances
in the order of the load queue. At this point the
plugin constructors are called. Plugins that other plugins depend on
are created first.
\li Sets the plugins to \c Loaded state.
\li Calls the \l{ExtensionSystem::IPlugin::initialize()}{initialize()} methods of
all plugins in the order of the load queue. In the \c initialize method,
a plugin should make sure that all exported interfaces are set up and available
to other plugins. A plugin can assume that plugins they depend on have set up
their exported interfaces. For example, the \c Core plugin sets up the
\l{Core::ActionManager}, \l{Core::EditorManager} and all other publicly available
interfaces, so other plugins can request and use them.
The \l{ExtensionSystem::IPlugin::initialize()}{initialize()} method of a plugin
is a good place for
\list
\li registering objects in the plugin manager's object pool
(see \l{The Plugin Manager, the Object Pool, and Registered Objects})
\li loading settings
\li adding new menus, and new actions to menus
\li connecting to other plugin's signals.
\endlist
\o Sets the plugins to \c Initialized state.
\li Sets the plugins to \c Initialized state.
\o Calls the \l{ExtensionSystem::IPlugin::extensionsInitialized()}{extensionsInitialized()}
methods of all plugins in \e reverse order of the load queue. After
the \c extensionsInitialized method, a plugin should be fully initialized, set up
and running. A plugin can assume that plugins that depend on it are fully set up,
and can finish the initialization of parts that can be extended by other plugins.
For example, the \c Core plugin assumes that all plugins have registered
their actions, and finishes initialization of the action manager.
\li Calls the \l{ExtensionSystem::IPlugin::extensionsInitialized()}{extensionsInitialized()}
methods of all plugins in \e reverse order of the load queue. After
the \c extensionsInitialized method, a plugin should be fully initialized, set up
and running. A plugin can assume that plugins that depend on it are fully set up,
and can finish the initialization of parts that can be extended by other plugins.
For example, the \c Core plugin assumes that all plugins have registered
their actions, and finishes initialization of the action manager.
\o Sets the plugins to \c Running state.
\li Sets the plugins to \c Running state.
\endlist
At the end of startup, the \c Core plugin's \l{Core::ICore} sends two signals.
......@@ -111,19 +111,19 @@
plugin manager starts its shutdown sequence:
\list 1
\o Calls the \l{ExtensionSystem::IPlugin::aboutToShutdown()}{aboutToShutdown()} methods of
all plugins in the order of the load queue. Plugins should perform measures
for speeding up the actual shutdown here, like disconnecting signals that
would otherwise needlessly be called.
If a plugin needs to delay the real shutdown for a while, for example if
it needs to wait for external processes to finish for a clean shutdown,
the plugin can return \l{ExtensionSystem::IPlugin::AsynchronousShutdown} from this
method. This will make the plugin manager wait with the next step, and keep the main
event loop running, until all plugins requesting AsynchronousShutdown have sent
the asynchronousShutdownFinished() signal.
\o Destroys all plugins by deleting their \l{ExtensionSystem::IPlugin}
instances in \e reverse order of the load queue. At this point the plugin destructors
are called. Plugins should clean up after themselves by freeing memory and other resources.
\li Calls the \l{ExtensionSystem::IPlugin::aboutToShutdown()}{aboutToShutdown()} methods of
all plugins in the order of the load queue. Plugins should perform measures
for speeding up the actual shutdown here, like disconnecting signals that
would otherwise needlessly be called.
If a plugin needs to delay the real shutdown for a while, for example if
it needs to wait for external processes to finish for a clean shutdown,
the plugin can return \l{ExtensionSystem::IPlugin::AsynchronousShutdown} from this
method. This will make the plugin manager wait with the next step, and keep the main
event loop running, until all plugins requesting AsynchronousShutdown have sent
the asynchronousShutdownFinished() signal.
\li Destroys all plugins by deleting their \l{ExtensionSystem::IPlugin}
instances in \e reverse order of the load queue. At this point the plugin destructors
are called. Plugins should clean up after themselves by freeing memory and other resources.
\endlist
*/
This diff is collapsed.
......@@ -44,48 +44,48 @@
\table
\header
\o Method
\o Description
\li Method
\li Description
\row
\o instance()
\o Returns the singleton plugin manager instance, for example for connecting to signals.
\li instance()
\li Returns the singleton plugin manager instance, for example for connecting to signals.
\row
\o addObject()
\o Registers an object in the object pool.
Also available through ExtensionSystem::IPlugin::addObject().
\li addObject()
\li Registers an object in the object pool.
Also available through ExtensionSystem::IPlugin::addObject().
\row
\o removeObject()
\o Unregisters an object from the object pool.
Also available through ExtensionSystem::IPlugin::removeObject().
\li removeObject()
\li Unregisters an object from the object pool.
Also available through ExtensionSystem::IPlugin::removeObject().
\row
\o getObjects<T>()
\o Returns all objects of type T that are registered in the object pool.
This respects \l{Aggregations}.
\li getObjects<T>()
\li Returns all objects of type T that are registered in the object pool.
This respects \l{Aggregations}.
\row
\o getObject<T>()
\o Returns one object of type T that is registered in the object pool.
This respects \l{Aggregations}.
\li getObject<T>()
\li Returns one object of type T that is registered in the object pool.
This respects \l{Aggregations}.
\row
\o getObjectByName(const QString &name)
\o Returns one object with the given object name that is registered in the object pool.
\li getObjectByName(const QString &name)
\li Returns one object with the given object name that is registered in the object pool.
\row
\o getObjectByClassName(const QString &className)
\o Returns one object with the given class name that is registered in the object pool.
\li getObjectByClassName(const QString &className)
\li Returns one object with the given class name that is registered in the object pool.
\endtable
\table
\header
\o Signal
\o Description
\li Signal
\li Description
\row
\o objectAdded(QObject *object)
\o Sent after an object is registered in the object pool.
\li objectAdded(QObject *object)
\li Sent after an object is registered in the object pool.
\row
\o aboutToRemoveObject(QObject *object)
\o Sent just before an object is unregistered from the object pool.
\li aboutToRemoveObject(QObject *object)
\li Sent just before an object is unregistered from the object pool.
\row
\o initializationDone()
\o Sent when plugins are running and all delayed initialization is done.
\li initializationDone()
\li Sent when plugins are running and all delayed initialization is done.
\endtable
\target object pool
......
......@@ -36,26 +36,26 @@
\table
\header
\o Library Name
\o Description
\li Library Name
\li Description
\row
\o \l{Aggregation}
\o Adds functionality for "glueing" QObjects of different
types together, so you can "cast" between them.
\li \l{Aggregation}
\li Adds functionality for "glueing" QObjects of different
types together, so you can "cast" between them.
\row
\o \l{ExtensionSystem}
\o Implements the plugin loader framework. Provides a base class for plugins and
basic mechanisms for plugin interaction like an object pool.
\li \l{ExtensionSystem}
\li Implements the plugin loader framework. Provides a base class for plugins and
basic mechanisms for plugin interaction like an object pool.
\row
\o \l{Utils}
\o General utility library.
\li \l{Utils}
\li General utility library.
\row
\o \l{QmlJS}
\o QML and JavaScript language support library.
\li \l{QmlJS}
\li QML and JavaScript language support library.
\endtable
......@@ -63,12 +63,12 @@
\table
\header
\o Library Name
\o Description
\li Library Name
\li Description
\row
\o \l{qtcreatorcdbext}
\o Windows CDB debugger extension
\li \l{qtcreatorcdbext}
\li Windows CDB debugger extension
\endtable
......@@ -82,38 +82,37 @@
\table
\header
\o Plugin Name
\o Description
\li Plugin Name
\li Description
\row
\o \l{Core}
\o The core plugin. Provides the main window and managers for editors,
\li \l