Add document on plugin life cycle.

Change-Id: Iec868cdb8158726d91bcece935a9d6269219c056
Reviewed-by: Leena Miettinen <riitta-leena.miettinen@nokia.com>

doc/api/plugin-lifecycle.qdoc

@@ -0,0 +1,122 @@
+/****************************************************************************
+**
+** This file is part of Qt Creator
+**
+** Copyright (c) 2011 Nokia Corporation and/or its subsidiary(-ies).
+**
+** Contact: Nokia Corporation (info@qt.nokia.com)
+**
+**
+** GNU Free Documentation License
+**
+** Alternatively, this file may be used under the terms of the GNU Free
+** Documentation License version 1.3 as published by the Free Software
+** Foundation and appearing in the file included in the packaging of this
+** file.
+**
+** If you have questions regarding the use of this file, please contact
+** Nokia at info@qt.nokia.com.
+**
+****************************************************************************/
+
+/*!
+    \page plugin-lifecycle.html
+    \title Plugin Life Cycle
+
+    To be able to write \QC plugins, you must understand the steps that the plugin
+    manager takes when you start or shut down \QC. This section describes
+    the process and the state that plugins go through in detail.
+
+    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 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.
+           \endlist
+
+        \o 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 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.
+    \endlist
+
+    At the end of startup, the \c Core plugin's \l{Core::ICore} sends two signals.
+    Before the \QC UI is shown it sends \l{Core::ICore::coreAboutToOpen()}{coreAboutToOpen()},
+    and afterwards \l{Core::ICore::coreOpened()}{coreOpened()}.
+
+    Before shutdown, the \c Core plugin's \l{Core::ICore} sends the
+    \l{Core::ICore::coreAboutToClose()}{coreAboutToClose()} signal. After that, the
+    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.
+    \endlist
+*/

doc/api/plugin-specifications.qdoc

@@ -180,7 +180,8 @@
     the \c{-help} command line argument, and the plugin manager does its command
     line parsing and sanity checks based on that information.
     If the plugin manager finds matching command line arguments for a plugin,
-    it passes them on to the plugin's \l{IPlugin::initialize} method.
+    it passes them on to the plugin's
+    \l{ExtensionSystem::IPlugin::initialize()}{initialize()} method.
 
     All command line argument definitions are enclosed by a single \c argumentList
     tag. The individual command line arguments are defined by the \c argument tag,

doc/doc.pri

@@ -55,6 +55,7 @@ DEV_HELP_DEP_FILES = \
     $$PWD/api/getting-and-building.qdoc \
     $$PWD/api/first-plugin.qdoc \
     $$PWD/api/plugin-specifications.qdoc \
+    $$PWD/api/plugin-lifecycle.qdoc \
     $$PWD/api/qtcreator-dev.qdocconf
 
 dev_html_docs.commands = $$qdoc($$OUT_PWD/doc/html-dev) $$PWD/api/qtcreator-dev.qdocconf