Harden internal documentation of QDockWidgetGroupWindow

QDockWidgetGroupWindow was documented by a few lines of code comments,
omitting the most critical part of its design: It must not become able
to acquire focus (i.e. be dragged or dropped) while having only one
QDockWidget child.

=> replace legacy code comments by structured internal documentation.

Pick-to: 6.6 6.5
Change-Id: I410ebf2e4c20c7479038417a4d8448dce8ab995f
Reviewed-by: Volker Hilsheimer <volker.hilsheimer@qt.io>

1 files changed, 34 insertions, 10 deletions

diff --git a/src/widgets/widgets/qmainwindowlayout.cpp b/src/widgets/widgets/qmainwindowlayout.cpp
index 9f26331ee9..52dec2efdf 100644
--- a/src/widgets/widgets/qmainwindowlayout.cpp
+++ b/src/widgets/widgets/qmainwindowlayout.cpp
@@ -168,16 +168,40 @@ static void dumpItemLists(const QMainWindowLayout *layout, const char *function,
 
 #endif // QT_CONFIG(dockwidget) && !defined(QT_NO_DEBUG)
 
-/******************************************************************************
- ** QDockWidgetGroupWindow
- */
-// QDockWidgetGroupWindow is the floating window containing several QDockWidgets floating together.
-// (QMainWindow::GroupedDragging feature)
-// QDockWidgetGroupLayout is the layout of that window and use a QDockAreaLayoutInfo to layout
-// the QDockWidgets inside it.
-// If there is only one QDockWidgets, or all QDockWidgets are tabbed together, it is equivalent
-// of a floating QDockWidget (the title of the QDockWidget is the title of the window). But if there
-// are nested QDockWidget, an additional title bar is there.
+
+/*!
+    \internal
+    QDockWidgetGroupWindow is a floating window, containing several QDockWidgets floating together.
+    This requires QMainWindow::GroupedDragging to be enabled.
+    QDockWidgets floating jointly in a QDockWidgetGroupWindow are considered to be docked.
+    Their \c isFloating property is \c false.
+    QDockWidget children of a QDockWidgetGroupWindow are either:
+    \list
+    \li tabbed (as long as Qt is compiled with the \c tabbar feature), or
+    \li arranged next to each other, equivalent to the default on a main window dock.
+    \endlist
+
+    QDockWidgetGroupWindow uses QDockWidgetGroupLayout to lay out its QDockWidget children.
+    It stores layout information in a QDockAreaLayoutInfo, including temporary spacer items
+    and rubber bands.
+
+    If its QDockWidget children are tabbed, the QDockWidgetGroupWindow shows the active QDockWidget's
+    title as its own window title.
+
+    QDockWidgetGroupWindow is designed to hold more than one QDockWidget.
+    A QDockWidgetGroupWindow with only one QDockWidget child may occur only temporarily
+    \list
+    \li in its construction phase, or
+    \li during a hover: While QDockWidget A is hovered over B, B is converted into a QDockWidgetGroupWindow.
+    \endlist
+
+    A QDockWidgetGroupWindow with only one QDockWidget child must never get focus, be dragged or dropped.
+    To enforce this restriction, QDockWidgetGrouWindow will remove itself after its second QDockWidget
+    child has been removed. It will make its last QDockWidget child a single, floating QDockWidget.
+    Eventually, the empty QDockWidgetGroupWindow will call deleteLater() on itself.
+*/
+
+
 #if QT_CONFIG(dockwidget)
 class QDockWidgetGroupLayout : public QLayout,
                                public QMainWindowLayoutSeparatorHelper<QDockWidgetGroupLayout>