Doc: Revise QWidget docs

Reviewing and improving the docs for QWidget is part of the objectives
for the 2023 Q4 OKRs.

Most of the work in this patch is fixing grammatical errors and typos.
It is tempting to move much, if not all, of the Detailed Description content from the QWidget class reference page (qwidget.cpp) into its own overview/explanation page, which would be more in line with the diátaxis framework. But I think that should be a different patch.

Fixes: QTBUG-117758
Pick-to: 6.6 6.5 6.2 5.15
Change-Id: Ibb3f367c4677f7e6615bc0cd39d0ffe921862cb9
Reviewed-by: Safiyyah Moosa <safiyyah.moosa@qt.io>
Reviewed-by: Topi Reiniö <topi.reinio@qt.io>

1 files changed, 32 insertions, 29 deletions

diff --git a/src/widgets/doc/src/windows-and-dialogs/mainwindow.qdoc b/src/widgets/doc/src/windows-and-dialogs/mainwindow.qdoc
index 827f7981ae..8e3db64de0 100644
--- a/src/widgets/doc/src/windows-and-dialogs/mainwindow.qdoc
+++ b/src/widgets/doc/src/windows-and-dialogs/mainwindow.qdoc
@@ -6,18 +6,20 @@
     \brief Windows and Dialogs in Qt.
     \ingroup qt-gui-concepts
 
-    A \l{Widgets Tutorial}{widget} that is not embedded in a parent widget is called a window.
-    (Usually, windows have a frame and a title bar, although it is also possible to create
-    windows without such decoration using suitable window flags). In Qt, QMainWindow
-    and the various subclasses of QDialog are the most common window types.
+    A \l{Widgets Tutorial}{widget} that is not embedded in a parent widget is
+    called a window. Usually, windows have a frame and a title bar, although it
+    is also possible to create windows without such decoration using suitable
+    window flags. In Qt, QMainWindow and the various subclasses of QDialog are
+    the most common window types.
 
     In applications, windows provide the screen space upon which the user
     interface is built. Windows separate applications visually from each other
-    and usually provide a window decoration that allows the user to resize and
-    position the applications according to his preferences. Windows are typically
-    integrated into the desktop environment and to some degree managed by the
-    window management system that the desktop environment provides. For instance,
-    selected windows of an application are represented in the task bar.
+    and usually provide a window decoration that allows you to resize and
+    position the applications according to your preferences. Windows are
+    typically integrated into the desktop environment and to some degree managed
+    by the window management system that the desktop environment provides. For
+    instance, selected windows of an application are represented in the task
+    bar.
 
     \section1 Primary and Secondary Windows
 
@@ -27,8 +29,8 @@
 
     In addition, a QWidget that has a parent can become a window by setting the
     Qt::Window flag. Depending on the window management system
-    such \e{secondary windows} are usually stacked on top of their respective parent
-    window, and not have a task bar entry of their own.
+    such \e{secondary windows} are usually stacked on top of their respective
+    parent window and do not have a task bar entry of their own.
 
     The QMainWindow class sets the Qt::Window flag in its constructor,
     as it is designed to be used as a window and provides facilities that are
@@ -37,13 +39,14 @@
     \section1 Main Windows and Dialogs
 
     The \l{Application Main Window} provides the framework for building the
-    application's main user interface, and are created by subclassing QMainWindow.
+    application's main user interface and are created by subclassing
+    QMainWindow.
     QMainWindow has its own layout to which you can add a \l{QMenuBar}{menu bar},
     \l{QToolBar}{tool bars}, \l{QDockWidget}{dockable widgets} and a
     \l{QStatusBar}{status bar}. The center area can be occupied by any kind of
     QWidget.
 
-    \l{Dialog Windows} are used as secondary windows that present the user with
+    \l{Dialog Windows} are used as secondary windows that present you with
     options and choices. Dialogs are created by subclassing QDialog and using
     \l{Widgets and Layouts}{widgets and layouts} to implement the user interface.
     In addition, Qt provides a number of ready-made standard dialogs that can be
@@ -59,8 +62,8 @@
 
     QWidget provides several functions that deal with a widget's
     geometry. Some of these functions operate on the pure client area
-    (i.e. the window excluding the window frame), others include the
-    window frame. The differentiation is done in a way that covers the
+    (that is, the window excluding the window frame), others include the
+    window frame. QWidget differentiates in a way that covers the
     most common usage transparently.
 
     \list
@@ -99,9 +102,9 @@
 
     Furthermore, a toolkit cannot simply place windows on the screen. All
     Qt can do is to send certain hints to the window manager. The window
-    manager, a separate process, may either obey, ignore or misunderstand
+    manager, a separate process, may either obey, ignore, or misunderstand
     them. Due to the partially unclear Inter-Client Communication
-    Conventions Manual (ICCCM), window placement is handled quite
+    Conventions Manual (ICCCM), window placement is handled
     differently in existing window managers.
 
     X11 provides no standard or easy way to get the frame geometry
@@ -137,8 +140,8 @@
     \section1 Overview of the Main Window Classes
 
     These classes provide everything you need for a typical modern main
-    application window, like the main window itself, menu and tool bars,
-    a status bar, etc.
+    application window, such as the main window itself, menu and tool bars,
+    and a status bar.
 
     \annotatedlist mainwindow-classes
 
@@ -148,8 +151,8 @@
     associated user interface components:
 
     \list
-    \li QMainWindow is the central class around which applications
-       can be built. Along with the companion QDockWidget and QToolBar
+    \li QMainWindow is the central class around which applications can be
+       built. Along with the companion QDockWidget and QToolBar
        classes, it represents the top-level user interface of the application.
 
     \li QDockWidget provides a widget that can be used to create
@@ -166,11 +169,11 @@
 
     \section1 Example Code
 
-    Using QMainWindow is straightforward. Generally, we subclass
+    Using QMainWindow is straightforward. Generally, you subclass
     QMainWindow and set up menus, toolbars, and dock widgets inside
     the QMainWindow constructor.
 
-    To add a menu bar to the main window, we simply create the menus, and
+    To add a menu bar to the main window, create the menus, and
     add them to the main window's menu bar. Note that the
     QMainWindow::menuBar() function will automatically create the menu bar
     the first time it is called. You can also call
@@ -181,8 +184,8 @@
     \snippet mainwindows/menus/mainwindow.cpp 5
     \dots
 
-    Once actions have been created, we can add them to the main window
-    components. To begin with, we add them to the pop-up menus:
+    Once actions have been created, you can add them to the main window
+    components. To begin with, add them to the pop-up menus:
 
     \snippet mainwindows/menus/mainwindow.cpp 10
     \dots
@@ -195,7 +198,7 @@
     provides this function, making it easy to reuse actions in different
     parts of the main window. This avoids unnecessary duplication of work.
 
-    We create a toolbar as a child of the main window, and add the desired
+    Create a toolbar as a child of the main window, and add the desired
     actions to it:
 
     \code
@@ -212,7 +215,7 @@
     newAct and \c openAct will be displayed both on the toolbar and in
     the file menu.
 
-    QDockWidget is used in a similar way to QToolBar. We create a
+    QDockWidget is used in a similar way to QToolBar. You create a
     dock widget as a child of the main window, and add widgets as children
     of the dock widget:
 
@@ -221,7 +224,7 @@
     In this example, the dock widget can only be placed in the left and
     right dock areas, and it is initially placed in the left dock area.
 
-    The QMainWindow API allows the programmer to customize which dock
+    The QMainWindow API lets you customize which dock
     widget areas occupy the four corners of the dock widget area. If
     required, the default can be changed with the
     QMainWindow::setCorner() function:
@@ -234,7 +237,7 @@
 
     \image mainwindow-docks-example.png
 
-    Once all of the main window components have been set up, the central widget
+    Once all the main window components have been set up, the central widget
     is created and installed by using code similar to the following:
 
     \snippet code/doc_src_qt4-mainwindow.cpp 3