From b0e5a30f62a853c39933c01364d63f2a793927e8 Mon Sep 17 00:00:00 2001
From: Eike Ziller <eike.ziller@qt.io>
Date: Thu, 4 Jun 2020 12:44:25 +0200
Subject: [PATCH] Add documentation for Core::IMode

Change-Id: I77893f203f521a12e5bd924bb292e76d03f878b2
Reviewed-by: Leena Miettinen <riitta-leena.miettinen@qt.io>
---
 src/plugins/coreplugin/imode.cpp | 99 +++++++++++++++++++++++++++++++-
 src/plugins/coreplugin/imode.h   |  7 ++-
 2 files changed, 104 insertions(+), 2 deletions(-)

diff --git a/src/plugins/coreplugin/imode.cpp b/src/plugins/coreplugin/imode.cpp
index 7c5fd8e9ad5..cfacb6b755d 100644
--- a/src/plugins/coreplugin/imode.cpp
+++ b/src/plugins/coreplugin/imode.cpp
@@ -27,12 +27,107 @@
 
 #include "modemanager.h"
 
-using namespace Core;
+namespace Core {
+
+/*!
+    \class Core::IMode
+    \ingroup mainclasses
+    \inmodule QtCreator
+    \inheaderfile coreplugin/imode.h
+
+    \brief The IMode class represents a mode in \QC.
+
+    This class defines a mode and its representation as a tool button in the
+    mode selector on the left side of \QC's main window.
+
+    Modes are used to show a different UI for different development tasks.
+    Therefore modes control the layout of most of Qt Creator's main window,
+    except for the tool bar on the left side and the status bar. For example
+    Edit mode, the most commonly used mode for coding, shows the code editor
+    and various navigation and output panes. Debug mode enhances that view with
+    a configurable layout of debugging related information. Design mode
+    reserves all the main window's space for the graphical editor.
+
+    A mode is an IContext. Set the context's \l{IContext::widget()}{widget}
+    to define the mode's layout.
+
+    Adding a mode should be done sparingly, only as a last reserve. Consider if
+    your feature can instead be implemented as a INavigationWidgetFactory,
+    IOutputPane, \c{Debugger::Utils::Perspective}, separate dialog, or
+    specialized IEditor first.
+
+    If you add a mode, consider adding a NavigationWidgetPlaceHolder
+    on the left side and a OutputPanePlaceHolder on the bottom of your
+    mode's layout.
+
+    Modes automatically register themselves with \QC when they are created and
+    unregister themselves when they are destructed.
+*/
+
+/*!
+    \property IMode::enabled
+
+    This property holds whether the mode is enabled.
+
+    By default, this property is \c true.
+*/
+
+/*!
+    \property IMode::displayName
+
+    This property holds the display name of the mode.
+
+    The display name is shown under the mode icon in the mode selector.
+*/
+
+/*!
+    \property IMode::icon
+
+    This property holds the icon of the mode.
+
+    The icon is shown for the mode in the mode selector. Mode icons should
+    support the sizes 34x34 pixels and 68x68 pixels for HiDPI.
+*/
+
+/*!
+    \property IMode::priority
+
+    This property holds the priority of the mode.
+
+    The priority defines the order in which the modes are shown in the mode
+    selector. Higher priority moves to mode towards the top. Welcome mode,
+    which should stay at the top, has the priority 100. The default priority is
+    -1.
+*/
+
+/*!
+    \property IMode::id
+
+    This property holds the ID of the mode.
+*/
+
+/*!
+    \property IMode::menu
+
+    This property holds the mode's menu.
+
+    By default, a mode does not have a menu. When you set a menu, it is not
+    owned by the mode unless you set the parent explicitly.
+*/
+
+/*!
+    Creates an IMode with an optional \a parent.
+
+    Registers the mode in \QC.
+*/
 IMode::IMode(QObject *parent) : IContext(parent)
 {
     ModeManager::instance()->addMode(this);
 }
 
+/*!
+    Unregisters the mode from \QC and destroys it.
+*/
 IMode::~IMode()
 {
     ModeManager::instance()->removeMode(this);
@@ -51,3 +146,5 @@ bool IMode::isEnabled() const
 {
     return m_isEnabled;
 }
+
+} // namespace Core
diff --git a/src/plugins/coreplugin/imode.h b/src/plugins/coreplugin/imode.h
index 80a819ae40b..fcbdcd3c485 100644
--- a/src/plugins/coreplugin/imode.h
+++ b/src/plugins/coreplugin/imode.h
@@ -36,7 +36,12 @@ namespace Core {
 class CORE_EXPORT IMode : public IContext
 {
     Q_OBJECT
-    Q_PROPERTY(bool enabled READ isEnabled WRITE setEnabled)
+    Q_PROPERTY(bool displayName READ displayName WRITE setDisplayName)
+    Q_PROPERTY(QIcon icon READ icon WRITE setIcon)
+    Q_PROPERTY(int priority READ priority WRITE setPriority)
+    Q_PROPERTY(Id id READ id WRITE setId)
+    Q_PROPERTY(QMenu *menu READ menu WRITE setMenu)
+    Q_PROPERTY(bool enabled READ isEnabled WRITE setEnabled NOTIFY enabledStateChanged)
 
 public:
     IMode(QObject *parent = nullptr);