Start on Creating Plugins documentation.

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

doc/api/coding-style.qdoc

@@ -517,6 +517,7 @@
 
     \section1 Patterns and Practices
 
+    \target coding-rules-namespacing
     \section2 Namespacing
 
     Read \l {http://wiki.qt-project.org/index.php/Qt_In_Namespace}{Qt In Namespace}

doc/api/creating-plugins.qdoc

@@ -0,0 +1,68 @@
+/****************************************************************************
+**
+** 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 creating-plugins.html
+    \title Creating Plugins
+
+    At its very core, \QC consists of a plugin loader that loads
+    and runs a set of plugins, which then actually provide the functionality
+    that you know from \QC the IDE. So, even the main application window
+    and menus are all provided by plugins. Plugins can use different means
+    to provide other plugins access to their functionality and to allow them
+    to extend certain aspects of the application.
+
+    For example the "Core" plugin, which is the very basic plugin that must be
+    present for \QC to run at all, provides the main window itself, and API
+    for adding menu items, modes, editor types, navigation panels and many other
+    things.
+    The "TextEditor" plugin provides a framework and base implementation for
+    different text editors with highlighting, completion and folding, that
+    is then used by other plugins to add more specialized text editor types
+    to \QC, like for editing C/C++ or .pro files.
+
+    After reading this guide you will know what a basic plugin consists of,
+    how to write a plugin specification file, what the lifecycle of a plugin is,
+    what the general principles for extending existing plugins'
+    functionality and providing interfaces for other plugins are, and will
+    be able to write your first plugin.
+
+    \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}
+    \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}
+    \endlist
+
+    \section1 Creating 3rd-Party Plugins
+    \list
+    \o \l{A Note on Binary Compatibility}
+    \o \l{Creating User-Installable Plugins}
+    \endlist
+*/

doc/api/examples/exampleplugin/Example.pluginspec.in

@@ -0,0 +1,17 @@
+//! [1]
+<plugin name=\"Example\" version=\"0.0.1\" compatVersion=\"0.0.1\">
+//! [1]
+//! [2]
+    <vendor>MyCompany</vendor>
+    <copyright>(C) MyCompany</copyright>
+    <license>BSD</license>
+    <description>Minimal plugin example</description>
+    <url>http://www.mycompany.com</url>
+//! [2]
+//! [3]
+    <dependencyList>
+        <dependency name=\"Core\" version=\"$$QTCREATOR_VERSION\"/>
+    </dependencyList>
+//! [3]
+</plugin>
+

doc/api/examples/exampleplugin/example.pro

@@ -0,0 +1,50 @@
+#! [1]
+TARGET = Example
+TEMPLATE = lib
+
+DEFINES += EXAMPLE_LIBRARY
+#! [1]
+
+# Example files
+
+#! [2]
+SOURCES += exampleplugin.cpp
+
+HEADERS += exampleplugin.h\
+        example_global.h\
+        exampleconstants.h
+#! [2]
+
+# Qt Creator linking
+
+#! [3]
+## set the QTC_SOURCE environment variable to override the setting here
+QTCREATOR_SOURCES = $$(QTC_SOURCE)
+isEmpty(QTCREATOR_SOURCES):QTCREATOR_SOURCES=/Users/example/qtcreator-src
+
+## set the QTC_BUILD environment variable to override the setting here
+IDE_BUILD_TREE = $$(QTC_BUILD)
+isEmpty(IDE_BUILD_TREE):IDE_BUILD_TREE=/Users/example/qtcreator-build
+#! [3]
+
+#! [4]
+## uncomment to build plugin into user config directory
+## <localappdata>/plugins/<ideversion>
+##    where <localappdata> is e.g.
+##    "%LOCALAPPDATA%\Nokia\qtcreator" on Windows Vista and later
+##    "$XDG_DATA_HOME/Nokia/qtcreator" or "~/.local/share/Nokia/qtcreator" on Linux
+##    "~/Library/Application Support/Nokia/Qt Creator" on Mac
+# USE_USER_DESTDIR = yes
+#! [4]
+
+#![5]
+PROVIDER = MyCompany
+#![5]
+
+#![6]
+include($$QTCREATOR_SOURCES/src/qtcreatorplugin.pri)
+include($$QTCREATOR_SOURCES/src/plugins/coreplugin/coreplugin.pri)
+
+LIBS += -L$$IDE_PLUGIN_PATH/Nokia
+#![6]
+

doc/api/examples/exampleplugin/example_global.h

@@ -0,0 +1,13 @@
+#ifndef EXAMPLE_GLOBAL_H
+#define EXAMPLE_GLOBAL_H
+
+#include <QtCore/QtGlobal>
+
+#if defined(EXAMPLE_LIBRARY)
+#  define EXAMPLESHARED_EXPORT Q_DECL_EXPORT
+#else
+#  define EXAMPLESHARED_EXPORT Q_DECL_IMPORT
+#endif
+
+#endif // EXAMPLE_GLOBAL_H
+

doc/api/examples/exampleplugin/exampleconstants.h

@@ -0,0 +1,14 @@
+#ifndef EXAMPLECONSTANTS_H
+#define EXAMPLECONSTANTS_H
+
+namespace Example {
+namespace Constants {
+
+const char ACTION_ID[] = "Example.Action";
+const char MENU_ID[] = "Example.Menu";
+
+} // namespace Example
+} // namespace Constants
+
+#endif // EXAMPLECONSTANTS_H
+

doc/api/examples/exampleplugin/exampleplugin.cpp

@@ -0,0 +1,88 @@
+#include "exampleplugin.h"
+#include "exampleconstants.h"
+
+#include <coreplugin/icore.h>
+#include <coreplugin/icontext.h>
+#include <coreplugin/actionmanager/actionmanager.h>
+#include <coreplugin/actionmanager/command.h>
+#include <coreplugin/actionmanager/actioncontainer.h>
+#include <coreplugin/coreconstants.h>
+
+#include <QtGui/QAction>
+#include <QtGui/QMessageBox>
+#include <QtGui/QMainWindow>
+#include <QtGui/QMenu>
+
+#include <QtCore/QtPlugin>
+
+using namespace Example::Internal;
+
+ExamplePlugin::ExamplePlugin()
+{
+    // Create your members
+}
+
+ExamplePlugin::~ExamplePlugin()
+{
+    // Unregister objects from the plugin manager's object pool
+    // Delete members
+}
+
+bool ExamplePlugin::initialize(const QStringList &arguments, QString *errorString)
+{
+    // Register objects in the plugin manager's object pool
+    // Load settings
+    // Add actions to menus
+    // Connect to other plugins' signals
+    // In the initialize method, a plugin can be sure that the plugins it
+    // depends on have initialized their members.
+
+    Q_UNUSED(arguments)
+    Q_UNUSED(errorString)
+
+//! [add action]
+    Core::ActionManager *am = Core::ICore::instance()->actionManager();
+
+    QAction *action = new QAction(tr("Example action"), this);
+    Core::Command *cmd = am->registerAction(action, Constants::ACTION_ID,
+                                            Core::Context(Core::Constants::C_GLOBAL));
+    cmd->setDefaultKeySequence(QKeySequence(tr("Ctrl+Alt+Meta+A")));
+    connect(action, SIGNAL(triggered()), this, SLOT(triggerAction()));
+//! [add action]
+//! [add menu]
+    Core::ActionContainer *menu = am->createMenu(Constants::MENU_ID);
+    menu->menu()->setTitle(tr("Example"));
+    menu->addAction(cmd);
+    am->actionContainer(Core::Constants::M_TOOLS)->addMenu(menu);
+//! [add menu]
+
+    return true;
+}
+
+void ExamplePlugin::extensionsInitialized()
+{
+    // Retrieve objects from the plugin manager's object pool
+    // In the extensionsInitialized method, a plugin can be sure that all
+    // plugins that depend on it are completely initialized.
+}
+
+ExtensionSystem::IPlugin::ShutdownFlag ExamplePlugin::aboutToShutdown()
+{
+    // Save settings
+    // Disconnect from signals that are not needed during shutdown
+    // Hide UI (if you add UI that is not in the main window directly)
+    return SynchronousShutdown;
+}
+
+//! [slot implementation]
+void ExamplePlugin::triggerAction()
+{
+    QMessageBox::information(Core::ICore::instance()->mainWindow(),
+                             tr("Action triggered"),
+                             tr("This is an action from Example."));
+}
+//! [slot implementation]
+
+//! [export plugin]
+Q_EXPORT_PLUGIN2(Example, ExamplePlugin)
+//! [export plugin]

doc/api/examples/exampleplugin/exampleplugin.h

@@ -0,0 +1,39 @@
+#ifndef EXAMPLE_H
+#define EXAMPLE_H
+
+#include "example_global.h"
+
+#include <extensionsystem/iplugin.h>
+
+//! [namespaces]
+namespace Example {
+namespace Internal {
+//! [namespaces]
+
+//! [base class]
+class ExamplePlugin : public ExtensionSystem::IPlugin
+{
+    Q_OBJECT
+//! [base class]
+
+public:
+    ExamplePlugin();
+    ~ExamplePlugin();
+
+//! [plugin methods]
+    bool initialize(const QStringList &arguments, QString *errorString);
+    void extensionsInitialized();
+    ShutdownFlag aboutToShutdown();
+//! [plugin methods]
+
+//! [slot]
+private slots:
+    void triggerAction();
+//! [slot]
+};
+
+} // namespace Internal
+} // namespace Example
+
+#endif // EXAMPLE_H
+

doc/api/first-plugin.qdoc

@@ -0,0 +1,334 @@
+/****************************************************************************
+**
+** 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 first-plugin.html
+    \title Creating Your First Plugin
+
+    This section describes how to create a \QC plugin by using the plugin
+    template provided by \QC, and get the first impression of what
+    a plugin consists of and what its general structure is.
+
+    \section1 Creating a Plugin Project
+
+    \QC comes with a wizard for \QC plugins, that creates a
+    runable, \e minimal plugin for you. We strongly suggest that you
+    use two different \QC instances for developing and testing
+    your plugin with. Otherwise your plugin will also be loaded in your
+    development environment, which can make that unstable while your
+    plugin is still unstable. You can just create a copy of your \QC
+    build and use one for actually developing, and the other for testing
+    your plugin with.
+
+    \list 1
+        \o Select \gui{File > New File or Project > Other Qt Project > Qt Creator Plugin > Choose}.
+
+           \image firstplugin-wizard.png "Choose the \QC Plugin Wizard"
+
+           The \gui{Introduction and Project Location} dialog opens.
+
+           \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.
+
+           The \gui{Target Setup} dialog opens.
+
+           \image firstplugin-target.png "Choose the Desktop Target and Matching Qt"
+
+        \o Select the target and Qt version to build your project with.
+           For a \QC plugin this needs to be the \gui{Desktop} target,
+           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.
+
+           \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.
+
+        \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).
+
+           \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.
+           \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/Nokia/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.
+    \endlist
+
+    \section1 Building and Running the Plugin
+
+    If you passed the correct \QC source and build paths in the project
+    wizard, your plugin should just build fine when pressing the build button.
+    When you try to run your project, \QC will ask you for the executable to run and
+    you are presented the following dialog:
+
+    \image firstplugin-runsettings.png "Specify the Executable to Run"
+
+    Select the path to the \QC executable from the build that you specified
+    in the \gui{Qt Creator build} setting in the project wizard and click \gui OK.
+    \QC starts up, and you can verify that your plugin successfully loaded
+    by looking for a menu entry \gui{Tools > Example} and by looking for
+    the plugin in the \gui{About Plugins} dialog.
+
+    \image firstplugin-menuitem.png "Menu Registered by the Plugin"
+
+    \section1 File Structure
+
+    The plugin wizard creates a set of basic files that a plugin needs or should have.
+    We will have a look at some of them in detail in the following sections, here is a short
+    overview:
+
+    \table
+    \header
+        \o File
+        \o 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.
+    \row
+        \o \c{example.pro}
+        \o 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.
+    \row
+        \o \c{exampleconstants.h}
+        \o 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
+           instanciated and run by \QC's plugin manager.
+    \endtable
+
+    \section1 qmake Project
+
+    The qmake project file \c{example.pro} defines how your plugin should be compiled.
+    \QC plugins need to have a specific setup there, in addition to telling qmake
+    which files need to be compiled (or handled by \c moc or \c uic).
+    Let us have a look at what the project wizard generated for you in detail.
+
+    \snippet exampleplugin/example.pro 1
+
+    The first section of the .pro file defines the very basic properties of your project,
+    the name (\c{TARGET}), and that a library should be generated,
+    since plugins are actually libraries that are dynamically loaded (\c{TEMPLATE = lib}).
+    The section also lets the compiler pass an \c EXAMPLE_LIBRARY define to the compiled
+    code, which is used in the \c{example_global.h} header, but is not really of interest
+    for now. You should not need to change that section of the .pro file.
+
+    \snippet exampleplugin/example.pro 2
+
+    This section tells qmake about the files of your project that it should let
+    compile or otherwise handle. You need to expand that section with any files
+    you add to the project.
+
+    \snippet exampleplugin/example.pro 3
+
+    To compile and deploy your plugin, the project needs access to the \QC sources and
+    build. This section contains the logic that looks for the information about
+    the location of the sources and build in the \c{QTC_SOURCE} and \c{QTC_BUILD}
+    environment variables. If these are not defined, it uses the defaults you
+    set in the project wizard.
+
+    So, if someone else opens your plugin project on their machine, they do not
+    need to edit the .pro file, but instead they should set the \c{QTC_SOURCE} and
+    \c{QTC_BUILD} environment variables correctly for the plugin's build environment.
+
+    You should not need to change this section, except perhaps to adapt the defaults.
+
+    \snippet exampleplugin/example.pro 4
+
+    \QC plugins can either be installed into the \QC installation's plugin directory
+    (requires write access there), or to a user specific plugin directory.
+    The \c USE_USER_DESTDIR switch in the .pro file defines which method is used for building
+    the plugin (which is independent from what you can later use for distributing your
+    plugin to other users).
+
+    \snippet exampleplugin/example.pro 5
+
+    The \c{PROVIDER} variable is for example used to deploy your plugin to a provider specific
+    plugin subdirectory, and the value is taken from the information that
+    you gave in the plugin project wizard.
+
+    \snippet exampleplugin/example.pro 6
+
+    This section includes the necessary parts from the \QC sources and makes your
+    plugin find the \QC libraries and plugins. The included file
+    \c{qtcreatorplugin.pri} makes sure that you build a plugin that is suitable
+    for use in \QC. The file \c{plugins/coreplugin/coreplugin.pri} makes your
+    plugin dependent on the Core plugin and makes sure that you can access its
+    public API.
+    If you want to use or extend functionality from other plugins, you
+    need to add the corresponding .pri file of the plugin here.
+
+    For more information about qmake, and writing .pro files in general,
+    see the \l{http://doc.qt.nokia.com/4.7/qmake-manual.html}{qmake Manual}.
+
+    \section1 Plugin Specification
+
+    The .pluginspec file is an XML file that contains information that is needed by
+    the plugin manager to find your plugin and resolve its dependencies before actually
+    loading your plugin's library file. We will only have a short look at it here.
+    For more information, see \l{Plugin Specifications}.
+
+    The wizard doesn't actually create a .pluginspec file directly, but instead a
+    .pluginspec.in file. qmake uses this to generate the actual plugin specification
+    file, replacing variables like \c{QTCREATOR_VERSION} with their actual values.
+    Therefore you need to escape all backslashes and quotes in the .pluginspec.in file
+    (i.e. you need to write \c{\\} to get a backslash and \c{\"} to get a quote
+    in the generated plugin specification).
+
+    \snippet exampleplugin/Example.pluginspec.in 1
+
+    The main tag of the plugin specification that is created by the wizard
+    defines the name of your plugin, its version, and with what version of this plugin
+    the current version is binary compatible with.
+
+    \snippet exampleplugin/Example.pluginspec.in 2
+
+    After the main tag you'll find the information about the plugin
+    that you gave in the project wizard.
+
+    \snippet exampleplugin/Example.pluginspec.in 3
+
+    The last section tells the plugin manager about the dependencies of this
+    plugin. Most \QC plugins will at least depend on the \c{Core} plugin.
+
+    \section1 Plugin Class
+
+    The files \c{exampleplugin.h} and \c{exampleplugin.cpp} define the plugin
+    implementation of your little plugin. We'll concentrate on some highlights
+    here, and give pointers to more detailed information for the various parts.
+
+    \section2 Header File
+
+    The header file \c{exampleplugin.h} defines the interface of the plugin class.
+
+    \snippet exampleplugin/exampleplugin.h namespaces
+
+    The plugin is defined in a \c{Example::Internal} namespace, which conforms to
+    the coding rules for \l{coding-rules-namespacing}{namespacing}
+    in \QC sources.
+
+    \snippet exampleplugin/exampleplugin.h base class
+
+    All \QC plugins must be derived from \l{ExtensionSystem::IPlugin} and
+    are QObjects.
+
+    \snippet exampleplugin/exampleplugin.h plugin methods
+
+    The base class defines basic methods that are called during the life cycle
+    of a plugin, which are here implemented for your new plugin.
+    These methods and their roles are described in detail in
+    \l{The Plugin Life Cycle}.
+
+    \snippet exampleplugin/exampleplugin.h slot
+
+    The plugin has an additional custom slot, that is used to pop up a dialog
+    when the user chooses the menu item that this plugin adds.
+
+    \section2 Source File
+
+    The source file contains the actual implementation of the plugin, which registers
+    a new menu and menu item, and opens a message box when that item is triggered.
+
+    All the necessary header files from the plugin code itself,
+    from the Core plugin, and from Qt are included in the beginning of the file.
+    The setup of the menu and menu item
+    is done in the plugin's \c{initialize} method, which is the first thing called
+    after the plugin constructor. In that method, the plugin can be sure that the basic
+    setup of plugin's that it depends on has been done, for example the Core plugin's
+    \c{ActionManager} instance has been created.
+
+    \snippet exampleplugin/exampleplugin.cpp add action
+
+    This part of the code creates a new \c{QAction}, registers it as a new
+    \c{Command} in the action manager, and connects it to the plugin's slot.
+    The action manager provides a central place where the user can assign and
+    change keyboard shortcuts, and manages cases where for example a menu item should be
+    directed to different plugins under different circumstances, as well as a few
+    other things. This is described in more detail in \l{Menus and Menu Items}.
+
+    \snippet exampleplugin/exampleplugin.cpp add menu
+
+    Here a new menu item is created, the created command added to it, and the menu
+    added to the \gui{Tools} menu in the menu bar. Again, this is covered in more
+    detail in \l{Menus and Menu Items}.
+
+    \snippet exampleplugin/exampleplugin.cpp slot implementation
+
+    This part defines the code that is called when the menu item is triggered.
+    It uses the Qt API to open a message box that displays informative text and
+    an \gui OK button.
+
+    \snippet exampleplugin/exampleplugin.cpp export plugin
+
+    At the end of the file, the Qt macro \c{Q_EXPORT_PLUGIN2} is used to register
+    the plugin with Qt's plugin loader system. This is necessary for Qt to
+    be able to load your plugin.
+
+*/

doc/api/getting-and-building.qdoc

@@ -0,0 +1,100 @@
+/****************************************************************************
+**
+** 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 getting-and-building.html
+    \title Getting and Building Qt Creator
+
+    \code
+    TODO: This should be extended.
+    * How to avoid building Qt
+    * Windows specific hassle, see README in \QC sources
+    \endcode
+
+    There are several reasons why you might want to do your own build of \QC,
+    like using the most current development version and being able to tweak
+    \QC at one or the other place. It is also necessary if you want to
+    create your own \QC plugin.
+
+    \section1 Getting and Building Qt
+
+    \QC usually uses the latest stable release of Qt,
+    you can see the exact minimum requirement at the top of \QC's qtcreator.pro.
+    (You can find the current version in our source repository here:
+    \l{https://qt.gitorious.org/qt-creator/qt-creator/blobs/master/qtcreator.pro}.)
+
+    You find the sources for the different Qt versions for example on our gitorious repository
+    \l{http://qt.gitorious.org/qt}.
+
+    \QC requires private headers of Qt, which are unfortunately not installed
+    by the Qt binary packages, and also are not copied to the installation directory when
+    using \c{make install} on a self-compiled Qt. To solve this problem
+    configure Qt with the \c{-developer-build} option, which sets the install
+    directory to the build directory itself (you are not required to run
+    \c{make install} in that case).
+    In Linux and Mac terminals, enter the following commands:
+    \code
+    cd <QtSources>
+    ./configure -developer-build
+    make
+    \endcode
+    On Windows, open a command prompt where your developer tools are set up, and enter
+    the following commands for MSVC builds
+    \code
+    cd <QtSources>
+    configure -developer-build
+    nmake
+    \endcode
+
+    If you really need to use a Qt build that does not have private headers in its
+    installation directory, you can set the \c{QT_PRIVATE_HEADERS} qmake variable
+    to the include path which contains them, when running qmake on the \QC
+    sources (see below).
+
+    \section1 Getting and Building \QC
+
+    You can get the \QC sources for a specific version either by using one of the
+    released source bundles, or from the Gitorious repository
+    \l{http://qt.gitorious.org/qt-creator}. If you intend to contribute to \QC
+    itself, you should use the repository from our Gerrit review tool as described
+    in the developer wiki here: \l{http://wiki.qt-project.org/Setting_up_Gerrit}.
+
+    We strongly encourage you to do out-of-source builds of \QC (also called
+    shadow-builds).
+    After you put the \QC sources somewhere (lets call the path \c{<QtCreatorSources>})
+    you build it on Linux and Mac with
+    \code
+    cd <QtCreatorSources>/..
+    mkdir qtcreator-build
+    cd qtcreator-build
+    <QtInstall>/bin/qmake -r <QtCreatorSources>
+    make
+    \endcode
+    or the corresponding commands on Windows systems.
+
+    If your Qt installation does not contain private headers (see above), you can point \QC
+    to the private headers by setting the \c{QT_PRIVATE_HEADERS} qmake variable
+    to the include directory that contains them. On Linux and Mac, enter the following command
+    instead of the qmake call above:
+    \code
+    <QtInstall>/bin/qmake -r QT_PRIVATE_HEADERS=<QtSources>/include <QtCreatorSources>
+    \endcode
+*/

doc/api/qtcreator-dev.qdoc

@@ -22,7 +22,6 @@
 /*!
     \page index.html
     \title Extending Qt Creator Manual
-    \nextpage
 
     Qt Creator is a cross-platform integrated development environment (IDE)
     tailored to the needs of Qt developers.

doc/config/qtcreator-developer.qdocconf

@@ -41,9 +41,9 @@ showinternal = true
 headers.fileextensions  = "*.h"
 sources.fileextensions  = "*.cpp *.qdoc"
 
-imagedirs = $SRCDIR/images $SRCDIR/templates/images
+imagedirs = $SRCDIR/api/images $SRCDIR/images $SRCDIR/templates/images
 outputdir = $OUTDIR
-exampledirs = ../api/examples
+exampledirs = $SRCDIR/api/examples
 indexes                 = qt.index
 
 include(compat.qdocconf)

doc/doc.pri

@@ -51,6 +51,9 @@ DEV_HELP_DEP_FILES = \
     $$PWD/api/external-tool-spec.qdoc \
     $$PWD/api/qtcreator-dev.qdoc \
     $$PWD/api/qtcreator-dev-wizards.qdoc \
+    $$PWD/api/creating-plugins.qdoc \
+    $$PWD/api/getting-and-building.qdoc \
+    $$PWD/api/first-plugin.qdoc \
     $$PWD/api/qtcreator-dev.qdocconf
 
 dev_html_docs.commands = $$qdoc($$OUT_PWD/doc/html-dev) $$PWD/api/qtcreator-dev.qdocconf

share/qtcreator/templates/wizards/qtcreatorplugin/myplugin.cpp

@@ -33,9 +33,9 @@ bool %PluginName%Plugin::initialize(const QStringList &arguments, QString *error
     // Register objects in the plugin manager's object pool
     // Load settings
     // Add actions to menus
-    // connect to other plugins' signals
-    // "In the initialize method, a plugin can be sure that the plugins it
-    //  depends on have initialized their members."
+    // Connect to other plugins' signals
+    // In the initialize method, a plugin can be sure that the plugins it
+    // depends on have initialized their members.
 
     Q_UNUSED(arguments)
     Q_UNUSED(errorString)
@@ -58,8 +58,8 @@ bool %PluginName%Plugin::initialize(const QStringList &arguments, QString *error
 void %PluginName%Plugin::extensionsInitialized()
 {
     // Retrieve objects from the plugin manager's object pool
-    // "In the extensionsInitialized method, a plugin can be sure that all
-    //  plugins that depend on it are completely initialized."
+    // In the extensionsInitialized method, a plugin can be sure that all
+    // plugins that depend on it are completely initialized.
 }
 
 ExtensionSystem::IPlugin::ShutdownFlag %PluginName%Plugin::aboutToShutdown()