Doc: Added some documentation

...to ioutputpane, inavigationwidgetfactory, ioptionspage and
removed now redundant comments

Authors:
    Falko Arps <fjarps@aol.com>
    Sven Klein <klein.sven@gmx.de>
    Giuliano Schneider <gs93@gmx.net>

Change-Id: I49651dfd4304a2e9a0ba2262a16f812d1fca773e
Reviewed-by: Eike Ziller <eike.ziller@digia.com>

src/plugins/coreplugin/actionmanager/actionmanager.cpp

@@ -54,6 +54,7 @@ using namespace Core::Internal;
 /*!
     \class Core::ActionManager
     \mainclass
+    \inmodule Qt Creator
 
     \brief The ActionManager class is responsible for registration of menus and
     menu items and keyboard shortcuts.
@@ -140,6 +141,18 @@ using namespace Core::Internal;
     \sa Core::IContext
 */
 
+/*!
+    \fn void ActionManager::commandListChanged()
+
+    Emitted when the command list has changed.
+*/
+
+/*!
+    \fn void ActionManager::commandAdded(const QString &id)
+
+    Emitted when a command (with the \a id) is added.
+*/
+
 static ActionManager *m_instance = 0;
 static ActionManagerPrivate *d;
 
@@ -162,8 +175,8 @@ ActionManager::~ActionManager()
 }
 
 /*!
- * \return Singleton action manager instance
- */
+    Returns the pointer to the instance, which is only used for connecting to signals.
+*/
 ActionManager *ActionManager::instance()
 {
     return m_instance;
@@ -330,8 +343,8 @@ ActionContainer *ActionManager::actionContainer(Id id)
 }
 
 /*!
- * Returns all commands that have been registered.
- */
+    Returns all commands that have been registered.
+*/
 QList<Command *> ActionManager::commands()
 {
     // transform list of CommandPrivate into list of Command
@@ -397,7 +410,11 @@ void ActionManager::unregisterShortcut(Id id)
     emit m_instance->commandListChanged();
 }
 
-
+/*!
+    Handles the display of the used shortcuts in the presentation mode. The presentation mode is
+    enabled when starting \QC with the command line argument \c{-presentationMode}. In the
+    presentation mode, \QC displays any pressed shortcut in a grey box.
+*/
 void ActionManager::setPresentationModeEnabled(bool enabled)
 {
     if (enabled == isPresentationModeEnabled())

src/plugins/coreplugin/coreplugin.pro

@@ -96,7 +96,8 @@ SOURCES += mainwindow.cpp \
     removefiledialog.cpp \
     iversioncontrol.cpp \
     dialogs/addtovcsdialog.cpp \
-    icorelistener.cpp
+    icorelistener.cpp \
+    ioutputpane.cpp
 
 HEADERS += mainwindow.h \
     editmode.h \

src/plugins/coreplugin/coreplugin.qbs

@@ -57,7 +57,7 @@ QtcPlugin {
             "imode.cpp", "imode.h",
             "inavigationwidgetfactory.cpp", "inavigationwidgetfactory.h",
             "infobar.cpp", "infobar.h",
-            "ioutputpane.h",
+            "ioutputpane.cpp", "ioutputpane.h",
             "iversioncontrol.cpp", "iversioncontrol.h",
             "mainwindow.cpp", "mainwindow.h",
             "manhattanstyle.cpp", "manhattanstyle.h",

src/plugins/coreplugin/dialogs/ioptionspage.cpp

 /****************************************************************************
 **
 ** Copyright (C) 2014 Digia Plc and/or its subsidiary(-ies).
+** Copyright (c) 2014 Falko Arps
+** Copyright (c) 2014 Sven Klein
+** Copyright (c) 2014 Giuliano Schneider
 ** Contact: http://www.qt-project.org/legal
 **
 ** This file is part of Qt Creator.
@@ -35,35 +38,103 @@
 #include <QPushButton>
 
 /*!
-  \class Core::IOptionsPage
-  \mainclass
-  \brief The IOptionsPage class is an interface for providing pages for the
-  \gui Options dialog (called \gui Preferences on Mac OS).
-
-  You need to subclass this interface and put an instance of your subclass
-  into the plugin manager object pool (e.g. ExtensionSystem::PluginManager::addObject).
-  Guidelines for implementing:
-  \list
-  \li \c id() is a unique identifier for referencing this page
-  \li \c displayName() is the (translated) name for display
-  \li \c category() is the unique id for the category that the page should be displayed in
-  \li \c displayCategory() is the translated name of the category
-  \li \c widget() is called to retrieve the widget to show in the
-        \gui Options dialog. You should create a widget lazily here, and delete it again in the
-        finish() method. This method can be called multiple times, so you should only create a new
-        widget if the old one was deleted.
-  \li \c apply() is called to store the settings. It should detect if any changes have been
-         made and store those
-  \li \c finish() is called directly before the \gui Options dialog closes. Here you should delete
-         the widget that was created in widget() to free resources.
-  \li \c matches() is used for the \gui Options dialog search filter. The default implementation
-         takes the widget() and searches for all labels, buttons, checkboxes and group boxes,
-         and matches on their texts/titles. You can implement your own matching algorithm, but
-         usually the default implementation will work fine.
-  \endlist
+    \class Core::IOptionsPage
+    \mainclass
+    \inmodule Qt Creator
+    \brief The IOptionsPage class is an interface for providing pages for the
+    \gui Options dialog (called \gui Preferences on Mac OS).
 */
 
+/*!
+
+    \fn Id IOptionsPage::id() const
+
+    Returns a unique identifier for referencing the options page.
+*/
+
+/*!
+    \fn QString IOptionsPage::displayName() const
+
+    Returns the translated display name of the options page.
+*/
+
+/*!
+    \fn Id IOptionsPage::category() const
+
+    Returns the unique id for the category that the options page should be displayed in. This id is
+    used for sorting the list on the left side of the \gui Options dialog.
+*/
+
+/*!
+    \fn QString IOptionsPage::displayCategory() const
+
+    Returns the translated category name of the options page. This name is displayed in the list on
+    the left side of the \gui Options dialog.
+*/
+
+/*!
+    \fn QIcon IOptionsPage::categoryIcon() const
+
+    Returns the category icon of the options page. This icon is displayed in the list on the left
+    side of the \gui Options dialog.
+*/
+
+/*!
+    \fn QWidget *IOptionsPage::widget()
+
+    Returns the widget to show in the \gui Options dialog. You should create a widget lazily here,
+    and delete it again in the finish() method. This method can be called multiple times, so you
+    should only create a new widget if the old one was deleted.
+*/
+
+/*!
+    \fn void IOptionsPage::apply()
+
+    This is called when selecting the \gui Apply button on the options page dialog. It should detect
+    whether any changes were made and store those.
+*/
+
+/*!
+    \fn void IOptionsPage::finish()
+
+    Is called directly before the \gui Options dialog closes. Here you should delete the widget that
+    was created in widget() to free resources.
+*/
+
+/*!
+    \fn void IOptionsPage::setId(Id id)
+
+    Sets the \a id of the options page.
+*/
+
+/*!
+    \fn void IOptionsPage::setDisplayName(const QString &displayName)
+
+    Sets \a displayName as the display name of the options page.
+*/
+
+/*!
+    \fn void IOptionsPage::setCategory(Id category)
+
+    Uses \a category to sort the options pages.
+*/
 
+/*!
+    \fn void IOptionsPage::setDisplayCategory(const QString &displayCategory)
+
+    Sets \a displayCategory as the display category of the options page.
+*/
+
+/*!
+    \fn void IOptionsPage::setCategoryIcon(const QString &categoryIcon)
+
+    Sets \a categoryIcon as the category icon of the options page.
+*/
+
+
+/*!
+    Constructs an options page with the given \a parent.
+*/
 Core::IOptionsPage::IOptionsPage(QObject *parent)
     : QObject(parent),
       m_keywordsInitialized(false)
@@ -71,10 +142,18 @@ Core::IOptionsPage::IOptionsPage(QObject *parent)
 
 }
 
+/*!
+    Destroys the options page.
+ */
 Core::IOptionsPage::~IOptionsPage()
 {
 }
 
+/*!
+    Is used by the \gui Options dialog search filter to match \a searchKeyWord to this options
+    page. This defaults to take the widget and then looks for all child labels, check boxes, push
+    buttons, and group boxes. Should return \c true when a match is found.
+*/
 bool Core::IOptionsPage::matches(const QString &searchKeyWord) const
 {
     if (!m_keywordsInitialized) {

src/plugins/coreplugin/inavigationwidgetfactory.cpp

 /****************************************************************************
 **
 ** Copyright (C) 2014 Digia Plc and/or its subsidiary(-ies).
+** Copyright (c) 2014 Falko Arps
+** Copyright (c) 2014 Sven Klein
+** Copyright (c) 2014 Giuliano Schneider
 ** Contact: http://www.qt-project.org/legal
 **
 ** This file is part of Qt Creator.
@@ -31,17 +34,85 @@
 
 #include <QKeySequence>
 
+/*!
+    \class Core::INavigationWidgetFactory
+    \mainclass
+    \inmodule Qt Creator
+    \brief The INavigationWidgetFactory class provides new instances of navigation widgets.
+
+    A navigation widget factory is necessary because there can be more than one navigation widget of
+    the same type at a time. Each navigation widget is wrapped in a \l{Core::NavigationView} for
+    delivery.
+*/
+
+/*!
+    \class Core::NavigationView
+    \inmodule Qt Creator
+    \brief The NavigationView class is a C struct for wrapping a widget and a list of tool buttons.
+    Wrapping the widget that is shown in the content area of the navigation widget and a list of
+    tool buttons that is shown in the header above it.
+*/
+
+/*!
+    \fn INavigationWidgetFactory::INavigationWidgetFactory()
+
+    Constructs a navigation widget factory.
+*/
+
+/*!
+    \fn QString INavigationWidgetFactory::displayName() const
+
+    Returns the display name of the navigation widget, which is shown in the dropdown menu above the
+    navigation widget.
+*/
+
+/*!
+    \fn int INavigationWidgetFactory::priority() const
+
+    Determines the position of the navigation widget in the dropdown menu.
+
+    0 to 1000 from top to bottom
+*/
+
+/*!
+    \fn Id INavigationWidgetFactory::id() const
+
+    Returns a unique identifier for referencing the navigation widget factory.
+*/
+
+/*!
+    \fn NavigationView INavigationWidgetFactory::createWidget()
+
+    Returns a \l{Core::NavigationView} containing the widget and the buttons. The ownership is given
+    to the caller.
+*/
+
 using namespace Core;
 
+/*!
+    Returns the keyboard shortcut to activate an instance of a navigation widget.
+*/
 QKeySequence INavigationWidgetFactory::activationSequence() const
 {
     return QKeySequence();
 }
 
+/*!
+    Stores the settings for the \a widget at \a position that was created by this factory
+    (the \a position identifies a specific navigation widget).
+
+    \sa INavigationWidgetFactory::restoreSettings()
+*/
 void INavigationWidgetFactory::saveSettings(int /* position */, QWidget * /* widget */)
 {
 }
 
+/*!
+    Reads and restores the settings for the \a widget at \a position that was created by this
+    factory (the \a position identifies a specific navigation widget).
+
+    \sa INavigationWidgetFactory::saveSettings()
+*/
 void INavigationWidgetFactory::restoreSettings(int /* position */, QWidget * /* widget */)
 {
 }

src/plugins/coreplugin/inavigationwidgetfactory.h

@@ -66,9 +66,6 @@ public:
     // Similar to how IView
     virtual NavigationView createWidget() = 0;
 
-    // Read and store settings for the widget, created by this factory
-    // and being at position position. (The position is important since
-    // a certain type of widget could exist multiple times.)
     virtual void saveSettings(int position, QWidget *widget);
     virtual void restoreSettings(int position, QWidget *widget);
 };

src/plugins/coreplugin/ioutputpane.cpp

+/****************************************************************************
+**
+** Copyright (c) 2014 Falko Arps
+** Copyright (c) 2014 Sven Klein
+** Copyright (c) 2014 Giuliano Schneider
+** Contact: http://www.qt-project.org/legal
+**
+** This file is part of Qt Creator.
+**
+** Commercial License Usage
+** Licensees holding valid commercial Qt licenses may use this file in
+** accordance with the commercial license agreement provided with the
+** Software or, alternatively, in accordance with the terms contained in
+** a written agreement between you and Digia.  For licensing terms and
+** conditions see http://qt.digia.com/licensing.  For further information
+** use the contact form at http://qt.digia.com/contact-us.
+**
+** GNU Lesser General Public License Usage
+** Alternatively, this file may be used under the terms of the GNU Lesser
+** General Public License version 2.1 as published by the Free Software
+** Foundation and appearing in the file LICENSE.LGPL included in the
+** packaging of this file.  Please review the following information to
+** ensure the GNU Lesser General Public License version 2.1 requirements
+** will be met: http://www.gnu.org/licenses/old-licenses/lgpl-2.1.html.
+**
+** In addition, as a special exception, Digia gives you certain additional
+** rights.  These rights are described in the Digia Qt LGPL Exception
+** version 1.1, included in the file LGPL_EXCEPTION.txt in this package.
+**
+****************************************************************************/
+
+#include "ioutputpane.h"
+
+/*!
+    \class Core::IOutputPane
+    \brief The IOutputPane class is an interface for providing \gui Output panes.
+
+    \mainclass
+    \inmodule Qt Creator
+*/
+
+/*!
+    \enum IOutputPane::Flag
+
+    This enum type controls the behavior of the output pane when it is requested to show itself.
+
+    \value NoModeSwitch
+                Does not switch between the modes.
+    \value ModeSwitch
+                Does switch between the modes.
+    \value WithFocus
+                Sets focus if canFocus returns true.
+    \value EnsureSizeHint
+                Ensures the use of the minimum size.
+*/
+
+/*!
+    \fn IOutputPane::IOutputPane(QObject *parent)
+
+    Constructs an output pane as the child of \a parent.
+*/
+
+/*!
+    \fn QWidget *IOutputPane::outputWidget(QWidget *parent)
+
+    Returns the output widget (as the child of \a parent) for the output pane.
+*/
+
+/*!
+    \fn QList<QWidget *> IOutputPane::toolBarWidgets() const
+
+    Returns the toolbar widgets for the output pane.
+*/
+
+/*!
+    \fn QString IOutputPane::displayName() const
+
+    Returns the translated display name of the output pane.
+*/
+
+/*!
+    \fn int IOutputPane::priorityInStatusBar() const
+
+    Determines the position of the output pane on the status bar.
+    \list
+        \li 100 to 0 from front to end
+        \li -1 do not show in status bar
+    \endlist
+*/
+
+/*!
+    \fn void IOutputPane::clearContents()
+
+    Is called on selecting the clear button.
+*/
+
+/*!
+    \fn void IOutputPane::visibilityChanged(bool visible)
+
+    Gets called when the visibility is changed. \a visible is \c true when the output pane is now
+    visible or \c false otherwise.
+*/
+
+/*!
+    \fn void IOutputPane::setFocus()
+
+    Gives focus to the output pane window.
+*/
+
+/*!
+    \fn bool IOutputPane::hasFocus() const
+
+    Returns \c true when the output pane has focus.
+
+    \sa IOutputPane::canFocus()
+*/
+
+/*!
+    \fn bool IOutputPane::canFocus() const
+
+    Returns \c true when the output pane can be focused right now (for example, the search
+    result window does not want to be focused if there are no results).
+*/
+
+/*!
+    \fn bool IOutputPane::canNavigate() const
+
+    Determines whether the output pane's navigation buttons can be enabled.
+    When this returns \c false, the buttons are disabled and cannot be enabled.
+
+    \sa IOutputPane::canNext()
+    \sa IOutputPane::canPrevious()
+*/
+
+/*!
+    \fn bool IOutputPane::canNext() const
+
+    Determines whether the \gui Next button in the output pane is enabled.
+    Is overwritten when \c canNavigate() returns \c false.
+
+    \sa IOutputPane::canNavigate()
+    \sa IOutputPane::canPrevious()
+    \sa IOutputPane::goToNext()
+*/
+
+/*!
+    \fn bool IOutputPane::canPrevious() const
+
+    Determines whether the \gui Previous button in the output pane is enabled.
+    Is overwritten when \c canNavigate() returns \c false.
+
+    \sa IOutputPane::canNavigate()
+    \sa IOutputPane::canNext()
+    \sa IOutputPane::goToPrev()
+*/
+
+/*!
+    \fn void IOutputPane::goToNext()
+
+    Is called on selecting the \gui Next button.
+
+    \sa IOutputPane::canNext()
+*/
+
+/*!
+    \fn void IOutputPane::goToPrev()
+
+    Is called on selecting the \gui Previous button.
+
+    \sa IOutputPane::canPrevious()
+*/
+
+/*!
+    \fn void IOutputPane::popup(int flags)
+
+    Emits the signal \c{showPage(int flags)} with the given parameter \a flags.
+
+    \sa IOutputPane::showPage()
+*/
+
+/*!
+    \fn void IOutputPane::hide()
+
+    Emits the signal \c hidePage().
+
+    \sa IOutputPane::hidePage()
+*/
+
+/*!
+    \fn void IOutputPane::toggle(int flags)
+
+    Emits the signal \c{togglePage(int flags)} with the given parameter \a flags.
+
+    \sa IOutputPane::togglePage()
+*/
+
+/*!
+    \fn void IOutputPane::navigateStateChanged()
+
+    Emits the signal \c navigateStateUpdate().
+
+    \sa IOutputPane::navigateStateUpdate()
+*/
+
+/*!
+    \fn void IOutputPane::flash()
+
+    Emits the signal \c flashButton().
+
+    \sa IOutputPane::flashButton()
+*/
+
+/*!
+    \fn void IOutputPane::setIconBadgeNumber(int number)
+
+    Emits the signal \c{setBadgeNumber(int number)} with the given parameter \a number.
+
+    \sa IOutputPane::setBadgeNumber()
+*/
+
+/*!
+    \fn void IOutputPane::showPage(int flags)
+
+    Shows the output pane. The parameter \a flags controls the behavior.
+
+    \sa IOutputPane::Flags
+*/
+
+/*!
+    \fn void IOutputPane::hidePage()
+
+    Hides the output pane.
+*/
+
+/*!
+    \fn void IOutputPane::togglePage(int flags)
+
+    Toggles the hide and show states of the output pane. The parameter \a flags controls the
+    behavior.
+
+    \sa IOutputPane::hidePage()
+    \sa IOutputPane::showPage()
+    \sa IOutputPane::Flags
+*/
+
+/*!
+    \fn void IOutputPane::navigateStateUpdate()
+
+    Notifies the output pane manager that the state of canNext, canPrevious, or canNavigate has
+    changed and the buttons need to be updated.
+*/
+
+/*!
+    \fn void IOutputPane::flashButton()
+
+    Makes the status bar button belonging to the output pane flash.
+*/
+
+/*!
+    \fn void IOutputPane::setBadgeNumber(int number)
+
+    Displays \a number in the status bar button belonging to the output pane
+    (for example, number of issues on building).
+*/

src/plugins/coreplugin/ioutputpane.h

@@ -53,19 +53,13 @@ public:
     virtual QList<QWidget *> toolBarWidgets() const = 0;
     virtual QString displayName() const = 0;
 
-    // -1 don't show in statusBar
-    // 100...0 show at front...end
     virtual int priorityInStatusBar() const = 0;
 
     virtual void clearContents() = 0;
     virtual void visibilityChanged(bool visible) = 0;
 
-    // This function is called to give the outputwindow focus
     virtual void setFocus() = 0;
-    // Whether the outputpane has focus
     virtual bool hasFocus() const = 0;
-    // Whether the outputpane can be focused at the moment.
-    // (E.g. the search result window does not want to be focused if the are no results.)
     virtual bool canFocus() const = 0;
 
     virtual bool canNavigate() const = 0;