Enhance the QWinThumbnailToolBar & QWinThumbnailToolButton docs

Change-Id: I1f82a537aea550a9c714284a19f79c31cb707ae7
Reviewed-by: Leena Miettinen <riitta-leena.miettinen@digia.com>

4 files changed, 70 insertions, 28 deletions

diff --git a/src/winextras/doc/snippets/code/thumbbar.cpp b/src/winextras/doc/snippets/code/thumbbar.cpp
index 6ee67c5..268a615 100644
--- a/src/winextras/doc/snippets/code/thumbbar.cpp
+++ b/src/winextras/doc/snippets/code/thumbbar.cpp
@@ -40,12 +40,12 @@
 
 #include <QtWinExtras>
 
-void initializeThumbnailToolBar(QWidget *window)
+void initializeThumbnailToolBar(QWidget *widget)
 {
-    Q_ASSERT(window->windowHandle()); // Note: this requires the window to be shown.
+    Q_ASSERT(widget->windowHandle()); // Note: this requires the window to be shown.
 //! [thumbbar_cpp]
-    QWinThumbnailToolBar *thumbbar = QWinThumbnailToolBar(window);
-    thumbbar->setWindow(window->windowHandle());
+    QWinThumbnailToolBar *thumbbar = QWinThumbnailToolBar(widget);
+    thumbbar->setWindow(widget->windowHandle());
 
     QWinThumbnailToolButton *settings = new QWinThumbnailToolButton(thumbbar);
     settings->setToolTip("Settings");
diff --git a/src/winextras/doc/src/qtwinextras-overview.qdoc b/src/winextras/doc/src/qtwinextras-overview.qdoc
index cf25928..77aacc2 100644
--- a/src/winextras/doc/src/qtwinextras-overview.qdoc
+++ b/src/winextras/doc/src/qtwinextras-overview.qdoc
@@ -1,6 +1,7 @@
 /****************************************************************************
 **
 ** Copyright (C) 2013 Ivan Vizir <define-true-false@yandex.com>
+** Copyright (C) 2013 Digia Plc and/or its subsidiary(-ies).
 ** Contact: http://www.qt-project.org/legal
 **
 ** This file is part of the documentation of the Qt Toolkit.
@@ -135,9 +136,9 @@
     \section2 Thumbnail Toolbar
 
     Applications can embed a toolbar in the thumbnail of a window, which is
-    shown when hovering over its taskbar icon. It provides quick access to the
-    window's commands without requiring the user to restore or activate the
-    window.
+    shown when hovering over its taskbar icon. A thumbnail toolbar may provide
+    quick access to the window's commands without requiring the user to restore
+    or activate the window.
 
     \image thumbbar.png Media player thumbnail toolbar
 
diff --git a/src/winextras/qwinthumbnailtoolbar.cpp b/src/winextras/qwinthumbnailtoolbar.cpp
index 06c5861..cc85b9c 100644
--- a/src/winextras/qwinthumbnailtoolbar.cpp
+++ b/src/winextras/qwinthumbnailtoolbar.cpp
@@ -1,6 +1,7 @@
 /****************************************************************************
  **
  ** Copyright (C) 2013 Ivan Vizir <define-true-false@yandex.com>
+ ** Copyright (C) 2013 Digia Plc and/or its subsidiary(-ies).
  ** Contact: http://www.qt-project.org/legal
  **
  ** This file is part of the QtWinExtras module of the Qt Toolkit.
@@ -61,12 +62,29 @@ static const int windowsLimitedThumbbarSize = 7;
     \class QWinThumbnailToolBar
     \inmodule QtWinExtras
     \since 5.2
-    \brief The QWinThumbnailToolBar class allows manipulating the window's thumbnail toolbar.
+    \brief The QWinThumbnailToolBar class allows manipulating the thumbnail toolbar of a window.
 
+    Applications can embed a toolbar in the thumbnail of a window, which is
+    shown when hovering over its taskbar icon. A thumbnail toolbar may provide
+    quick access to the commands of a window without requiring the user to restore
+    or activate the window.
+
+    \image thumbbar.png Media player thumbnail toolbar
+
+    The following example code illustrates how to use the functions in the
+    QWinThumbnailToolBar and QWinThumbnailToolButton class to implement a
+    thumbnail toolbar:
+
+    \snippet code/thumbbar.cpp thumbbar_cpp
+
+    \sa QWinThumbnailToolButton
  */
 
 /*!
-    Constructs a QWinThumbnailToolBar with the parent object \a parent.
+    Constructs a QWinThumbnailToolBar with the specified \a parent.
+
+    If \a parent is an instance of QWindow, it is automatically
+    assigned as the thumbnail toolbar's \l window.
  */
 QWinThumbnailToolBar::QWinThumbnailToolBar(QObject *parent) :
     QObject(parent), d_ptr(new QWinThumbnailToolBarPrivate)
@@ -78,7 +96,7 @@ QWinThumbnailToolBar::QWinThumbnailToolBar(QObject *parent) :
 }
 
 /*!
-    Destroys the QWinThumbnailToolBar and clears the toolbar.
+    Destroys and clears the QWinThumbnailToolBar.
  */
 QWinThumbnailToolBar::~QWinThumbnailToolBar()
 {
@@ -114,9 +132,9 @@ QWindow *QWinThumbnailToolBar::window() const
 }
 
 /*!
-    Appends a \a button to the right of the thumbnail toolbar.
+    Adds a \a button to the thumbnail toolbar.
 
-    \note The number of buttons is limited to 7.
+    \note The number of buttons is limited to \c 7.
  */
 void QWinThumbnailToolBar::addButton(QWinThumbnailToolButton *button)
 {
@@ -138,7 +156,7 @@ void QWinThumbnailToolBar::addButton(QWinThumbnailToolButton *button)
 }
 
 /*!
-    Removes the \a button from this toolbar.
+    Removes the \a button from the thumbnail toolbar.
  */
 void QWinThumbnailToolBar::removeButton(QWinThumbnailToolButton *button)
 {
@@ -152,7 +170,9 @@ void QWinThumbnailToolBar::removeButton(QWinThumbnailToolButton *button)
 }
 
 /*!
-    Replaces the currently set toolbar with \a buttons.
+    Sets the list of \a buttons in the thumbnail toolbar.
+
+    \note Any existing buttons are replaced.
  */
 void QWinThumbnailToolBar::setButtons(const QList<QWinThumbnailToolButton *> &buttons)
 {
@@ -164,7 +184,7 @@ void QWinThumbnailToolBar::setButtons(const QList<QWinThumbnailToolButton *> &bu
 }
 
 /*!
-    Returns the list of buttons which this toolbar consists of.
+    Returns the list of buttons in the thumbnail toolbar.
  */
 QList<QWinThumbnailToolButton *> QWinThumbnailToolBar::buttons() const
 {
@@ -174,7 +194,9 @@ QList<QWinThumbnailToolButton *> QWinThumbnailToolBar::buttons() const
 
 /*!
     \property QWinThumbnailToolBar::count
-    \brief the current button count
+    \brief the number of buttons in the thumbnail toolbar
+
+    \note The number of buttons is limited to \c 7.
  */
 int QWinThumbnailToolBar::count() const
 {
@@ -183,7 +205,7 @@ int QWinThumbnailToolBar::count() const
 }
 
 /*!
-    Removes all buttons from the toolbar.
+    Removes all buttons from the thumbnail toolbar.
  */
 void QWinThumbnailToolBar::clear()
 {
diff --git a/src/winextras/qwinthumbnailtoolbutton.cpp b/src/winextras/qwinthumbnailtoolbutton.cpp
index 6cce3e1..af1f7f5 100644
--- a/src/winextras/qwinthumbnailtoolbutton.cpp
+++ b/src/winextras/qwinthumbnailtoolbutton.cpp
@@ -1,6 +1,7 @@
 /****************************************************************************
  **
  ** Copyright (C) 2013 Ivan Vizir <define-true-false@yandex.com>
+ ** Copyright (C) 2013 Digia Plc and/or its subsidiary(-ies).
  ** Contact: http://www.qt-project.org/legal
  **
  ** This file is part of the QtWinExtras module of the Qt Toolkit.
@@ -48,7 +49,15 @@ QT_BEGIN_NAMESPACE
     \class QWinThumbnailToolButton
     \inmodule QtWinExtras
     \since 5.2
-    \brief The QWinThumbnailToolButton class represents a button in the window's thumbnail toolbar.
+    \brief The QWinThumbnailToolButton class represents a button in a thumbnail toolbar.
+
+    Buttons in a QWinThumbnailToolBar are instances of QWinThumbnailToolButton.
+    It provides a set of properties for specifying the attributes of a thumbnail
+    toolbar button. It also provides a signal that is emitted whenever the button
+    is \l{clicked()}{clicked}, and a slot to perform \l{click()}{clicks}
+    programmatically.
+
+    \sa QWinThumbnailToolBar
  */
 
 /*!
@@ -119,7 +128,12 @@ QIcon QWinThumbnailToolButton::icon() const
     \property QWinThumbnailToolButton::enabled
     \brief whether the button is enabled
 
-    This property's default is true.
+    The default value is \c true.
+
+    A disabled button does not react to user interaction,
+    and is also visually disabled.
+
+    \sa interactive
  */
 void QWinThumbnailToolButton::setEnabled(bool enabled)
 {
@@ -140,11 +154,13 @@ bool QWinThumbnailToolButton::isEnabled() const
     \property QWinThumbnailToolButton::interactive
     \brief whether the button is interactive
 
-    This property's default is true.
+    The default value is \c true.
+
+    A non-interactive button does not react to user interaction,
+    but is still visually enabled. A typical use case for non-
+    interactive buttons are notification icons.
 
-    If not interactive, the button remains enabled, but no pressed or mouse-over
-    states are drawn. Set this property to false to use this button as a
-    notification icon.
+    \sa enabled
  */
 void QWinThumbnailToolButton::setInteractive(bool interactive)
 {
@@ -165,7 +181,7 @@ bool QWinThumbnailToolButton::isInteractive() const
     \property QWinThumbnailToolButton::visible
     \brief whether the button is visible
 
-    This property's default is true.
+    The default value is \c true.
  */
 void QWinThumbnailToolButton::setVisible(bool visible)
 {
@@ -186,7 +202,7 @@ bool QWinThumbnailToolButton::isVisible() const
     \property QWinThumbnailToolButton::dismissOnClick
     \brief whether the window thumbnail is dismissed after a button click
 
-    This property's default is false.
+    The default value is \c false.
  */
 void QWinThumbnailToolButton::setDismissOnClick(bool dismiss)
 {
@@ -205,9 +221,11 @@ bool QWinThumbnailToolButton::dismissOnClick() const
 
 /*!
     \property QWinThumbnailToolButton::flat
-    \brief whether the button background and frame are not drawn
+    \brief whether the button is flat
+
+    The default value is \c false.
 
-    This property's default is false.
+    A flat button does not draw a background nor a frame - only an icon.
  */
 void QWinThumbnailToolButton::setFlat(bool flat)
 {
@@ -227,7 +245,8 @@ bool QWinThumbnailToolButton::isFlat() const
 /*!
     Performs a click. The clicked() signal is emitted as appropriate.
 
-    Does nothing if the button is disabled or non-interactive.
+    This function does nothing if the button is \l{enabled}{disabled}
+    or \l{interactive}{non-interactive}.
  */
 void QWinThumbnailToolButton::click()
 {