Doc: Update documentation for Document Viewer demo

The source code has seen multiple revisions and the documentation
was referring to types and implementation details that no longer
exist or hold true.

Reorganize the content, simplify the language, and fix the source
file quoting.

Change-Id: If22c052460b4dc2f1e321eb423c6f2a415cd26f5
Reviewed-by: Axel Spoerl <axel.spoerl@qt.io>
Reviewed-by: Andreas Eliasson <andreas.eliasson@qt.io>

2 files changed, 147 insertions, 153 deletions

diff --git a/examples/demos/documentviewer/app/recentfiles.h b/examples/demos/documentviewer/app/recentfiles.h
index d9bb2eb8..e65d62be 100644
--- a/examples/demos/documentviewer/app/recentfiles.h
+++ b/examples/demos/documentviewer/app/recentfiles.h
@@ -35,9 +35,9 @@ public:
     void setOpenMode(QIODevice::OpenMode mode) { m_openMode = mode; }
 
 public slots:
-    void addFile(const QString &fileName) {addFile(fileName, EmitPolicy::EmitWhenChanged); }
+    void addFile(const QString &fileName) { addFile(fileName, EmitPolicy::EmitWhenChanged); }
     void addFiles(const QStringList &fileNames);
-    void removeFile(const QString &fileName) {removeFile(indexOf(fileName)); }
+    void removeFile(const QString &fileName) { removeFile(indexOf(fileName)); }
     void removeFile(qsizetype index) {removeFile(index, RemoveReason::RemovedManually); }
     void saveSettings(QSettings &settings, const QString &key) const;
     bool restoreFromSettings(QSettings &settings, const QString &key);
diff --git a/examples/demos/documentviewer/doc/src/documentviewer.qdoc b/examples/demos/documentviewer/doc/src/documentviewer.qdoc
index f153b6f6..ddcee81b 100644
--- a/examples/demos/documentviewer/doc/src/documentviewer.qdoc
+++ b/examples/demos/documentviewer/doc/src/documentviewer.qdoc
@@ -5,298 +5,292 @@
     \title Document Viewer
     \ingroup examples-widgets
     \example demos/documentviewer
+    \meta {tag} {demo,widgets,mainwindow}
     \brief A Widgets application to display and print JSON, text, and PDF files.
 
-    Demonstrates various features to use in widget applications:
+
+    \e{Document Viewer} demonstrates how to use a QMainWindow with static
+    and dynamic toolbars, menus, and actions. Additionally, it demonstrates
+    the following features in widget-based applications:
+
     \list
-    \li Using QSettings, query and save user preferences, manage file histories and
-    \li Controllinh cursor behavior when hovering over widgets.
-    \li Writing and dynamically loading plugins.
+        \li Using QSettings to query and save user preferences,
+            and managing previously opened file history.
+        \li Controlling cursor behavior when hovering over widgets.
+        \li Creating dynamically loaded plugins.
     \endlist
 
     \image documentviewer_open.png
-    \meta {tag} {demo,widgets,mainwindow}
 
-    \e{Document Viewer} demonstrates how to use a QMainWindow with static
-    and dynamic tool bars, menus and actions.
-
-    The MainWindow class provides a common application screen with general menus,
-    actions and a tool bar. It provides functionality to open a file, determine the
-    content type and keep a list of previously opened files. It stores information
-    in QSettings and reads settings when launched.
-    Depending on the opened file's content type, it creates a suitable viewer to
-    display it and provide printing functionality.
 
-    \section1 Creating an executable
+    \section1 Creating an application and the main window
 
-    To create an executable, we use a standard main.cpp file.
-    First, we set the application's organization name:
+    The application and its main window is constructed in \c main.cpp.
+    The main() function uses QCommandLineParser to process command line
+    arguments -- \e help, \e version, and an optional positional
+    argument, \e file. If the user provided a path to a file when
+    launching the application, the main window opens it:
 
     \quotefromfile demos/documentviewer/app/main.cpp
     \skipto int main
-    \printuntil QApplication::set
-    \endsection1
+    \printuntil exec
+    \printline }
 
-    \section1 Creating an application and showing the main window
-
-    \quotefromfile demos/documentviewer/app/main.cpp
-    \skipto QApplication app
-    \printuntil }
-    \endsection1
 
-    \section1 The MainWindow class
+    \section1 MainWindow class
 
-    The class constructor initializes the user interface created in Qt Designer.
-    It links the actions for opening a file and the about dialog to their implementation.
+    The \c MainWindow class provides an application screen with menus,
+    actions, and a toolbar. It can open a file, automatically detecting its
+    content type. It also maintains a list of previously opened files, using
+    QSettings to store and reload settings when launched. The MainWindow
+    creates a suitable \e viewer for the opened file, based on its content type,
+    and provides support for printing a document.
 
-    \quotefromfile demos/documentviewer/app/mainwindow.cpp
-    \skipto ui->setupUi
-    \printuntil triggered
+    MainWindow's constructor initializes the user interface created in Qt
+    Designer. The \c mainwindow.ui file provides a QTabWidget on the left,
+    showing bookmarks and thumbnails. On the right, there is a QScrollArea for
+    viewing file content.
 
-    The \c mainwindow.ui file provides a QTabWidget on the left, where bookmarks and thumbnails
-    can be displayed. It provides a QScrollArea on the right, where the viewed file contents are
-    \printuntil showMenu);
 
-    If a file is opened, the {File} class (inheriting from {QFile}) automatically determines
-    the FileType used in this application. If no valid file type could be established, the user
-    is asked, if it should be opened as plain text.
+    \section1 ViewerFactory class
 
-    The \c ViewerFactory class is used to manage file type specific viewers, implemented as plugins.
-    When an instance of \c ViewerFactory is created, pointers to view area and QMainWindow have
-    to be passed to the constructor.
+    The \c ViewerFactory class manages viewers for known file types. These viewers
+    are implemented as plugins. When an instance of a ViewerFactory is created,
+    pointers to the view area and the main window are passed to the constructor:
 
     \code
     m_factory.reset(new ViewerFactory(ui->viewArea, this));
     \endcode
 
-    \c ViewerFactory loads all available plugins when constructed. It provides public APIs to
-    query about loaded plugins, their names, and supported mime types.
+    ViewerFactory loads all available plugins on construction. It provides
+    a public API to query the loaded plugins, their names, and supported MIME
+    types:
 
     \quotefromfile demos/documentviewer/app/viewerfactory.h
     \skipto ViewerList
     \printuntil QStringList supportedMimeTypes() const;
 
-
-    The method \c viewer returns the pointer to the plugin suitable to open the QFile passed
-    as an argument.
+    The \c viewer() function returns a pointer to the plugin suitable to open
+    the QFile passed as an argument:
 
     \code
     m_viewer = m_factory->viewer(file);
     \endcode
 
-    If the application settings contain a section for the viewer, it is passed to the viewer's
-    virtual restoreState method. Afterwards, the standard UI assets are passed to the viewer
-    and it's display widget is displayed in the main scroll area.
+    If the application settings contain a section for the viewer, it's passed
+    to the viewer's virtual \c restoreState() function:
+
+    \quotefromfile demos/documentviewer/app/mainwindow.cpp
+    \skipto MainWindow::restoreViewerSettings
+    \printuntil restoreState
+    \printline }
+
+    Then, the standard UI assets are passed to the viewer and the main scroll
+    area is set to show the viewer's display widget:
 
     \quotefromfile demos/documentviewer/app/mainwindow.cpp
     \skipuntil void MainWindow::openFile
     \skipto m_viewer->initViewer
     \printuntil }
-    \endsection1
-
-    \section1 The ViewerFactory class
 
-    The only static method of the class takes a file, the widget where the viewed content is to be
-    displayed, the main window and the user questions.
-    Depending on the file's mime type, it creates an appropriate document viewer.
 
-    \quotefromfile demos/documentviewer/app/mainwindow.cpp
-    \skipto AbstractViewer
-    \printuntil }
-    \endsection1
+    \section1 AbstractViewer class
 
-    \section1 The AbstractViewer class
+    \c AbstractViewer provides a generalized API to view, save, and print a
+    document. Properties of both the document and the viewer can be queried:
 
-    The class provides a generalized API to view and browse through a document, save and print it.
-    Properties of the document and the viewer itself can be queried: Does the document have content?
-    Has it been modified? Is an overview (thumbnails or bookmarks) supported?
-    The viewer's state can be saved to and restored from a QByteArray, which the application can
-    access to store in its settings.
+    \list
+        \li Does the document have content?
+        \li Has it been modified?
+        \li Is an overview (thumbnails or bookmarks) supported?
+    \endlist
 
-    AbstractViewer provides protected methods for classes inheriting from it, to create actions
-    and menus on the main window. In order to display these assets on the main window, they are
-    parented to it. AbstractViewer takes responsibility to remove and destroy the UI assets it
-    created. It inherits from QObject to provide access to signals and slots.
+    AbstractViewer provides protected methods for derived classes to create
+    actions and menus on the main window. In order to display these
+    assets on the main window, they are parented to it. AbstractViewer is
+    responsible for removing and destroying the UI assets it creates. It
+    inherits from QObject to implement signals and slots.
 
     \section2 Signals
 
+    \c {void uiInitialized();}
 
-    \code
-    void uiInitialized();
-    \endcode
+    This signal is emitted after a viewer receives all necessary information
+    about UI assets on the main window.
 
-    The signal is emitted when AbstractViewer has received all necessary information about UI
-    assets on the main window.
+    \c {void printingEnabledChanged(bool enabled);}
 
-    \code
-    void printingEnabledChanged(bool enabled);
-    \endcode
+    This signal is emitted when document printing is either enabled or
+    disabled. This happens after a new document was successfully loaded,
+    or, for example, all content was removed.
 
-    This signal is emitted when document printing has been enabled or disabled, e.g. because a new
-    document has been successfully loaded or all content has been removed.
+    \c {void printStatusChanged(AbstractViewer::PrintStatus status);}
 
-    \code
-    void printStatusChanged(AbstractViewer::PrintStatus status);
-    \endcode
+    After starting the printing process, this signal notifies about changes in
+    its progress.
 
-    When printing has been started, this signal notifies about the printing progress.
+    \c {void documentLoaded(const QString &fileName);}
 
-    \code
-    void documentLoaded(const QString &fileName);
-    \endcode
-    \endsection2
+    This signal notifies the application that a document was successfully
+    loaded.
+
+
+    \section1 TxtViewer class
+
+    \c TxtViewer is a simple text viewer, inheriting from AbstractViewer.
+    It supports editing text files, copy/cut and paste, printing, and
+    saving changes.
 
-    The signal notifies the application that a document has been loaded successfully.
-    \endsection1
 
-    \section1 The TextViewer class
+    \section1 JsonViewer class
 
-    A simple text viewer, inheriting from AbstractViewer.
-    It features editing text files, copy/cut and paste, printing and saving changes.
+    \c JsonViewer displays a JSON file in a QTreeView. Internally, it loads
+    the contents of a file into a QJsonDocument and uses it to populate a
+    custom tree model with \c JsonItemModel.
 
-    \section1 The JsonViewer class
+    The JSON viewer plugin demonstrates how to implement a custom item model
+    inherited from QAbstractItemModel. The \c JsonTreeItem class provides a
+    basic API for manipulating JSON data and propagating it back to the
+    underlying QJsonDocument.
 
-    The plugin class displays a JSON file in a QTreeView.
-    It loads a file into a QJsonDocument, used to populate a custom tree model with
-    JsonItemModel.
-    This part of the JSON viewer demonstrates, how to implement custom item models inheriting from
-    QAbstractItemModel. The JsonTreeItem class provides basic API for manipulating JSON data
-    and propagating it back to the underlying QJsonDocument.
+    JsonViewer uses the top-level objects of the document as bookmarks for
+    navigation. Other nodes (keys and values) can be added as additional
+    bookmarks, or removed from the bookmark list. A QLineEdit is used as a
+    search field to navigate through the JSON tree.
 
-    JsonViewer uses the toplevel objects as bookmarks for navigation. Other nodes (keys or
-    values) can be added as additional bookmarks or removed from the bookmark list.
-    A QLineEdit is used as a search field to navigate through the JSON tree.
-    \endsection1
 
-    \section1 The PdfViewer class
-    This plugin is a fork of the QPdfViewerWidgets example.
-    It demonstrates the use of QScroller to smoothly flick through the document.
+    \section1 PdfViewer class
 
-    \section1 The TxtViewer class
-    This plugin is a simple a text editor, to show how a user interface is written in pure C++.
-    \endsection1
+    The \c PdfViewer class (and plugin) is a fork of the \l {PDF Viewer
+    Widget Example}. It demonstrates the use of QScroller to smoothly
+    flick through a document.
 
-    \section1 Additional classes for application features
 
-    \section2 The HoverWatcher class
+    \section1 Other relevant classes
 
-    The class can be used to set override cursors when the mouse is hovering over a widget and
-    to restore them upon departure.
-    In order to prevent multiple HoverWatcher instances created for the same widget, it is
+    \section2 HoverWatcher class
+
+    The \c HoverWatcher class sets an override cursor when hovering the
+    mouse over a widget, restoring it upon departure. To prevent multiple
+    HoverWatcher instances being created for the same widget, it is
     implemented as a singleton per widget.
 
-    HoverWatcher inherits from QObject and the QWidget watched becomes the instance's parent.
-    An event filter is used to intercept the hover events without consuming them.
+    HoverWatcher inherits from QObject and takes the QWidget it watches
+    as the instance's parent. It installs an event filter to intercept hover
+    events without consuming them:
 
     \quotefromfile demos/documentviewer/plugins/pdfviewer/hoverwatcher.cpp
     \skipto HoverWatcher::HoverWatcher
     \printuntil }
 
-    The actions watched are represented in an enum.
+    The \c HoverAction enum lists the actions that HoverWatcher reacts to:
 
     \quotefromfile demos/documentviewer/plugins/pdfviewer/hoverwatcher.h
     \skipto enum HoverAction
     \printuntil };
 
-    Static methods create watchers, check their existence for a specific QWidget or dismiss
-    a watcher.
+    Static functions create watchers, check their existence for a specific
+    QWidget, or dismiss a watcher:
 
     \quotefromfile demos/documentviewer/plugins/pdfviewer/hoverwatcher.h
     \skipto static HoverWatcher
     \printuntil static void dismiss
 
-    A cursor shape can be specified or unset for each HoverAction. If no cursor shape is
-    specified for an action, the application's override cursor will be restored when it occurs.
+    A cursor shape can be set or unset for each HoverAction. If there is
+    no associated cursor shape, the application's override cursor is
+    restored when the action is triggered.
 
     \quotefromfile demos/documentviewer/plugins/pdfviewer/hoverwatcher.h
     \skipto public slots
     \printuntil void unSetCursorShape
 
-    The mouseButtons property specifies, which mouse buttons to consider for the MousePress action.
+    The \c mouseButtons property holds the mouse buttons to consider for a
+    \c MousePress action:
 
     \quotefromfile demos/documentviewer/plugins/pdfviewer/hoverwatcher.h
     \skipuntil public slots
     \skipto setMouseButtons
     \printuntil setMouseButton(
 
-    Action specific signals are emitted when an action has been processed.
+    Action-specific signals are emitted after processing an action:
 
     \quotefromfile demos/documentviewer/plugins/pdfviewer/hoverwatcher.h
     \skipto signals
     \printuntil left();
 
-    A general signal is emitted which passes the processed action as an argument.
+    A general signal is emitted which passes the processed action as an
+    argument:
 
     \code
     void hoverAction(HoverAction action);
     \endcode
-    \endsection2
 
-    \section2 The {RecentFiles} class
+    \section2 RecentFiles class
 
-    The class is a QStringList, specialized to manage a list of recently opened files.
+    \c RecentFiles is a QStringList that is specialized to manage a list of
+    recently opened files.
 
     \quotefromfile demos/documentviewer/app/recentfiles.cpp
     \skipto RecentFiles::RecentFiles
     \printuntil }
 
-    It provides slots to add a single or multiple files, by passing their path or a list
-    of paths as an argument. A file is added, if the path leads to a valid file.
-    If a file already exists in the list of recent files, it is removed from its original position
-    and added on the top.
+    RecentFiles has slots to add either a single file or multiple files in one
+    go. An entry is added to the list of recent files if the path points to a
+    file that exists and can be opened. If a file is already in the list, it
+    is removed from its original position and added to the top.
 
     \quotefromfile demos/documentviewer/app/recentfiles.h
     \skipto public slots
     \printuntil addFiles
 
-    Files can be removed by name or by index.
+    Files are removed from the list either by name or by index:
 
     \quotefromfile demos/documentviewer/app/recentfiles.h
     \skipuntil public slots
     \skipto removeFile
-    \printuntil addFiles
+    \printuntil qsizetype index
 
-    Slots are available to save and restore from {QSettings}.
-    Files restored from settings are ignored, if they no longer exist.
+    Slots that implement saving and restoring from QSettings:
 
     \quotefromfile demos/documentviewer/app/recentfiles.h
     \skipuntil public slots
     \skipto saveSettings
     \printuntil restoreFromSettings
 
-    The maxFiles property manages the maximum amount of recent files to be remebered (default: 10).
+    When restoring settings, nonexistent files are ignored. The \c maxFiles
+    property holds the maximum amount of recent files to store (default is
+    10).
 
     \code
     qsizetype maxFiles();
     void setMaxFiles(qsizetype maxFiles);
     \endcode
 
-    {RecentFiles} verifies a file can be opened in {openMode}, before adding it.
+    \c {RecentFiles} verifies that a file can be opened in \c {openMode} before
+    accepting it.
 
     \code
     void setOpenMode(QIODevice::OpenMode mode);
     QIODevice::OpenMode openMode() const;
     \endcode
-    \endsection2
 
-    \section2 The {RecentFileMenu} class
+    \section2 RecentFileMenu class
 
-    The {RecentFileMenu} class is a QMenu, specialized as a submenu to display a \l{RecentFiles}
-    object as a submenu.
+    \c {RecentFileMenu} is a QMenu, specialized to display a
+    \l{RecentFiles class}{RecentFiles} object as a submenu.
 
-    Its constructor takes a parent widget, usually and QAction or a QMenu.
-    Its fileOpened signal passes a QString argument with the absolute file name, when the
-    application user has selected a recent file from the list.
+    Its constructor takes a pointer to a parent QObject and a pointer to a
+    RecentFiles object, the content of which it will visualize.
+    Its \c fileOpened() signal, triggered when the user selects a recent file
+    from the list, passes the absolute path to the file as an argument.
 
-    \note
-    A {RecentFileMenu} is deleted either with its parent widget, or with the RecentFiles object
-    passed to its constructor.
+    \note \c {RecentFileMenu} is destroyed either by its parent widget, or by the
+          \c {RecentFiles} object passed to its constructor.
 
     \quotefromfile demos/documentviewer/app/recentfilemenu.h
-    \skipuntil class RecentFileMenu
+    \skipto class RecentFileMenu
     \printuntil void fileOpened
-
-    \endsection2
-    \endsection1
-
+    \dots
+    \skipuntil RecentFiles
+    \printline }
 */