Documentation and example improvements

Mark relevant bits of the examples as snippets and use those in the
reference documentation.

Replace very short slots in the C++ example with lambdas.

Change-Id: I8deeeda7924f1721676147718e9a6fbdd408aaa0
Reviewed-by: Axel Spoerl <axel.spoerl@qt.io>
(cherry picked from commit ed0bafb89a0245c6ea14b59ed177ecbcbe83a2d5)
Reviewed-by: Qt Cherry-pick Bot <cherrypick_bot@qt-project.org>

4 files changed, 70 insertions, 21 deletions

diff --git a/examples/speech/hello_speak/mainwindow.cpp b/examples/speech/hello_speak/mainwindow.cpp
index 3d4ef68..84f5cf2 100644
--- a/examples/speech/hello_speak/mainwindow.cpp
+++ b/examples/speech/hello_speak/mainwindow.cpp
@@ -7,8 +7,7 @@
 #include <QLoggingCategory>
 
 MainWindow::MainWindow(QWidget *parent)
-    : QMainWindow(parent),
-    m_speech(nullptr)
+    : QMainWindow(parent), m_speech(nullptr)
 {
     ui.setupUi(this);
     QLoggingCategory::setFilterRules(QStringLiteral("qt.speech.tts=true \n qt.speech.tts.*=true"));
@@ -21,22 +20,12 @@ MainWindow::MainWindow(QWidget *parent)
     ui.engine->setCurrentIndex(0);
     engineSelected(0);
 
-    connect(ui.speakButton, &QPushButton::clicked, this, &MainWindow::speak);
     connect(ui.pitch, &QSlider::valueChanged, this, &MainWindow::setPitch);
     connect(ui.rate, &QSlider::valueChanged, this, &MainWindow::setRate);
     connect(ui.volume, &QSlider::valueChanged, this, &MainWindow::setVolume);
     connect(ui.engine, &QComboBox::currentIndexChanged, this, &MainWindow::engineSelected);
 }
 
-void MainWindow::speak()
-{
-    m_speech->say(ui.plainTextEdit->toPlainText());
-}
-void MainWindow::stop()
-{
-    m_speech->stop();
-}
-
 void MainWindow::setRate(int rate)
 {
     m_speech->setRate(rate / 10.0);
@@ -52,6 +41,7 @@ void MainWindow::setVolume(int volume)
     m_speech->setVolume(volume / 100.0);
 }
 
+//! [stateChanged]
 void MainWindow::stateChanged(QTextToSpeech::State state)
 {
     if (state == QTextToSpeech::Speaking) {
@@ -67,6 +57,7 @@ void MainWindow::stateChanged(QTextToSpeech::State state)
     ui.resumeButton->setEnabled(state == QTextToSpeech::Paused);
     ui.stopButton->setEnabled(state == QTextToSpeech::Speaking || state == QTextToSpeech::Paused);
 }
+//! [stateChanged]
 
 void MainWindow::engineSelected(int index)
 {
@@ -93,9 +84,24 @@ void MainWindow::engineSelected(int index)
     setRate(ui.rate->value());
     setPitch(ui.pitch->value());
     setVolume(ui.volume->value());
-    connect(ui.stopButton, &QPushButton::clicked, m_speech, [this]{ m_speech->stop(); });
-    connect(ui.pauseButton, &QPushButton::clicked, m_speech, [this]{ m_speech->pause(); });
+//! [say]
+    connect(ui.speakButton, &QPushButton::clicked, m_speech, [this]{
+        m_speech->say(ui.plainTextEdit->toPlainText());
+    });
+//! [say]
+//! [stop]
+    connect(ui.stopButton, &QPushButton::clicked, m_speech, [this]{
+        m_speech->stop();
+    });
+//! [stop]
+//! [pause]
+    connect(ui.pauseButton, &QPushButton::clicked, m_speech, [this]{
+        m_speech->pause();
+    });
+//! [pause]
+//! [resume]
     connect(ui.resumeButton, &QPushButton::clicked, m_speech, &QTextToSpeech::resume);
+//! [resume]
 
     connect(m_speech, &QTextToSpeech::stateChanged, this, &MainWindow::stateChanged);
     connect(m_speech, &QTextToSpeech::localeChanged, this, &MainWindow::localeChanged);
diff --git a/examples/speech/hello_speak/mainwindow.h b/examples/speech/hello_speak/mainwindow.h
index 91484b0..aaa1632 100644
--- a/examples/speech/hello_speak/mainwindow.h
+++ b/examples/speech/hello_speak/mainwindow.h
@@ -19,9 +19,6 @@ public:
     MainWindow(QWidget *parent = 0);
 
 public slots:
-    void speak();
-    void stop();
-
     void setRate(int);
     void setPitch(int);
     void setVolume(int volume);
diff --git a/examples/speech/quickspeech/main.qml b/examples/speech/quickspeech/main.qml
index 651f8c2..8e069e4 100644
--- a/examples/speech/quickspeech/main.qml
+++ b/examples/speech/quickspeech/main.qml
@@ -13,12 +13,15 @@ ApplicationWindow {
     minimumWidth: inputForm.implicitWidth
     minimumHeight: inputForm.implicitHeight + footer.implicitHeight
 
+//! [initialize]
     TextToSpeech {
         id: tts
         volume: volumeSlider.value
         pitch: pitchSlider.value
         rate: rateSlider.value
+//! [initialize]
 
+//! [stateChanged]
         onStateChanged: (state) => {
             switch (state) {
                 case TextToSpeech.Ready:
@@ -35,6 +38,13 @@ ApplicationWindow {
                     break
             }
         }
+//! [stateChanged]
+
+//! [sayingWord]
+        onSayingWord: (start, length)=> {
+            input.select(start, start + length)
+        }
+//! [sayingWord]
     }
 
     ColumnLayout {
@@ -49,26 +59,34 @@ ApplicationWindow {
             Layout.fillWidth: true
             Layout.minimumHeight: implicitHeight
         }
+//! [say0]
         RowLayout {
             Button {
                 text: qsTr("Speak")
                 enabled: [TextToSpeech.Paused, TextToSpeech.Ready].includes(tts.state)
                 onClicked: {
+//! [say0]
                     let voices = tts.availableVoices()
                     tts.voice = voices[voicesComboBox.currentIndex]
+//! [say1]
                     tts.say(input.text)
                 }
             }
+//! [say1]
+//! [pause]
             Button {
                 text: qsTr("Pause")
                 enabled: tts.state == TextToSpeech.Speaking
                 onClicked: tts.pause()
             }
+//! [pause]
+//! [resume]
             Button {
                 text: qsTr("Resume")
                 enabled: tts.state == TextToSpeech.Paused
                 onClicked: tts.resume()
             }
+//! [resume]
             Button {
                 text: qsTr("Stop")
                 enabled: [TextToSpeech.Speaking, TextToSpeech.Paused].includes(tts.state)
diff --git a/src/tts/qtexttospeech.cpp b/src/tts/qtexttospeech.cpp
index ac8faa8..8152f48 100644
--- a/src/tts/qtexttospeech.cpp
+++ b/src/tts/qtexttospeech.cpp
@@ -144,8 +144,15 @@ void QTextToSpeechPrivate::loadPluginMetadata(QMultiHash<QString, QCborMap> &lis
     \brief The QTextToSpeech class provides a convenient access to text-to-speech engines.
     \inmodule QtTextToSpeech
 
-    Use \l say() to start synthesizing text, and \l stop(), \l pause(), and \l resume()
-    to control the reading of the text.
+    Use \l say() to start reading text to the default audio device, and
+    \l stop(), \l pause(), and \l resume() to control the reading of the text.
+
+    \snippet hello_speak/mainwindow.cpp say
+    \snippet hello_speak/mainwindow.cpp stop
+    \snippet hello_speak/mainwindow.cpp pause
+    \snippet hello_speak/mainwindow.cpp resume
+
+    To synthesize text into PCM data for further processing, use synthesize().
 
     The list of voices the engine supports for the current language is returned by
     \l availableVoices(). Change the language using \l setLocale(), using one of the
@@ -164,8 +171,20 @@ void QTextToSpeechPrivate::loadPluginMetadata(QMultiHash<QString, QCborMap> &lis
     \inqmlmodule QtTextToSpeech
     \brief The TextToSpeech type provides access to text-to-speech engines.
 
-    Use \l say() to start synthesizing text, and \l stop(), \l pause(), and \l resume()
-    to control the reading of the text.
+    Use \l say() to start reading text to the default audio device, and
+    \l stop(), \l pause(), and \l resume() to control the reading of the text.
+
+    \snippet quickspeech/main.qml initialize
+    \codeline
+    \dots
+    \codeline
+    \snippet quickspeech/main.qml say0
+    \snippet quickspeech/main.qml say1
+    \snippet quickspeech/main.qml pause
+    \snippet quickspeech/main.qml resume
+    \dots
+
+    To synthesize text into PCM data for further processing, use synthesize().
 
     The list of voices the engine supports for the current language is returned by
     \l availableVoices(). Change the language using the \l locale property, using one
@@ -369,12 +388,16 @@ QStringList QTextToSpeech::availableEngines()
     \brief This property holds the current state of the speech synthesizer.
 
     \sa QTextToSpeech::State say() stop() pause()
+
+    \snippet quickspeech/main.qml stateChanged
 */
 
 /*!
     \property QTextToSpeech::state
     \brief the current state of the speech synthesizer.
 
+    \snippet hello_speak/mainwindow.cpp stateChanged
+
     Use \l say() to start synthesizing text with the current \l voice and \l locale.
 */
 QTextToSpeech::State QTextToSpeech::state() const
@@ -455,6 +478,9 @@ QString QTextToSpeech::errorString() const
     This function starts sythesizing the speech asynchronously, and reads the text to the
     default audio output device.
 
+    \snippet quickspeech/main.qml say0
+    \snippet quickspeech/main.qml say1
+
     \note All in-progress readings are stopped before beginning to read the recently
     synthesized text.
 
@@ -471,6 +497,8 @@ QString QTextToSpeech::errorString() const
     This function starts sythesizing the speech asynchronously, and reads the text to the
     default audio output device.
 
+    \snippet hello_speak/mainwindow.cpp say
+
     \note All in-progress readings are stopped before beginning to read the recently
     synthesized text.