Document the QML types

Pick-to: 6.4
Change-Id: I2d0bf694f1e9bad3c200887997fcdc069e444463
Reviewed-by: Volker Hilsheimer <volker.hilsheimer@qt.io>

3 files changed, 221 insertions, 25 deletions

diff --git a/src/tts/doc/src/qttexttospeech-index.qdoc b/src/tts/doc/src/qttexttospeech-index.qdoc
index 24bb266..c755aa6 100644
--- a/src/tts/doc/src/qttexttospeech-index.qdoc
+++ b/src/tts/doc/src/qttexttospeech-index.qdoc
@@ -7,15 +7,15 @@
    \brief The Qt TextToSpeech module enables access to text-to-speech engines
 
    The module enables a Qt application to support accessibility features such
-   as text-to-speech, which is useful for end-users who are visually
-   challenged or cannot access the application for whatever reason. The
-   most common use case where text-to-speech comes in handy is when the
-   end-user is driving and cannot attend the incoming messages on the phone.
-   In such a scenario, the messaging application can read out the incoming
-   message.
-
-   The module depends on Speech Dispatcher (libspeechd) on the Linux platform.
-   On other platforms, it uses the native APIs to access the
+   as text-to-speech, which is useful for end-users who cannot access the
+   application's visual interface. In addition to assistive technologies like
+   screen readers, the most common use case for text-to-speech is when the
+   end-user is driving or operating machinery. In such a scenario, an application
+   can use text-to-speech to read out incoming notifications, or to provide
+   turn-by-turn navigation instructions.
+
+   On Linux, the module can use the Speech Dispatcher daemon (libspeechd), or
+   flite. On other platforms, it uses the native system APIs to access the
    platform-specific text-to-speech engines.
 
    \section1 Using the Module
@@ -52,7 +52,7 @@
 
    The following lists some important C++ Classes.
 
-   \annotatedlist qttexttospeech-module
+   \annotatedlist qttexttospeech_cpp
 
    \section1 Reference and Examples
 
diff --git a/src/tts/qtexttospeech.cpp b/src/tts/qtexttospeech.cpp
index 36c42e8..e6c1355 100644
--- a/src/tts/qtexttospeech.cpp
+++ b/src/tts/qtexttospeech.cpp
@@ -143,6 +143,7 @@ void QTextToSpeechPrivate::loadPluginMetadata(QMultiHash<QString, QCborMap> &lis
     \class QTextToSpeech
     \brief The QTextToSpeech class provides a convenient access to text-to-speech engines.
     \inmodule QtTextToSpeech
+    \ingroup qttexttospeech_cpp
 
     Use \l say() to start synthesizing text, and \l stop(), \l pause(), and \l resume()
     to control the reading of the text.
@@ -150,9 +151,6 @@ void QTextToSpeechPrivate::loadPluginMetadata(QMultiHash<QString, QCborMap> &lis
     It is possible to specify the language with \l setLocale(). To set a voice, get the
     list of \l availableVoices() and set the desired voice using \l setVoice(). The list
     of available voices depends on the active locale on most platforms.
-
-    The languages and voices depend on the available synthesizers on each platform.
-    On Linux, \c speech-dispatcher is used by default.
 */
 
 /*!
@@ -160,6 +158,13 @@ void QTextToSpeechPrivate::loadPluginMetadata(QMultiHash<QString, QCborMap> &lis
     \inqmlmodule QtTextToSpeech
     \ingroup texttospeech_qml
     \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.
+
+    It is possible to specify the language with \l locale. To set a \l voice, get the
+    list of \l availableVoices() and set the desired \l Voice. The list of available
+    voices depends on the active locale on most platforms.
 */
 
 /*!
@@ -281,6 +286,17 @@ QTextToSpeech::~QTextToSpeech()
 }
 
 /*!
+    \qmlproperty string TextToSpeech::engine
+
+    The engine used to synthesize text to speech.
+
+    Changing the engine stops any ongoing speech.
+
+    On most platforms, changing the engine will update the list of
+    \l{availableLocales()}{available locales} and \l{availableVoices()}{available voices}.
+*/
+
+/*!
     \property QTextToSpeech::engine
     \brief the engine used to synthesize text to speech.
     \since 6.4
@@ -321,6 +337,12 @@ QString QTextToSpeech::engine() const
 }
 
 /*!
+    \qmlmethod list<string> TextToSpeech::availableEngines()
+
+    Holds the list of supported text-to-speech engine plug-ins.
+*/
+
+/*!
     Gets the list of supported text-to-speech engine plug-ins.
 
     \sa engine
@@ -331,6 +353,13 @@ QStringList QTextToSpeech::availableEngines()
 }
 
 /*!
+    \qmlproperty enumeration TextToSpeech::state
+    \brief This property holds the current state of the speech synthesizer.
+
+    \sa QTextToSpeech::State say() stop() pause()
+*/
+
+/*!
     \property QTextToSpeech::state
     \brief the current state of the speech synthesizer.
 
@@ -345,6 +374,16 @@ QTextToSpeech::State QTextToSpeech::state() const
 }
 
 /*!
+    \qmlsignal void TextToSpeech::errorOccured(enumeration reason, string errorString)
+
+    This signal is emitted after an error occurred and the \l state has been set to
+    \c TextToSpeech.Error. The \a reason parameter specifies the type of error,
+    and the \a errorString provides a human-readable error description.
+
+    \sa state errorReason(), errorString()
+*/
+
+/*!
     \fn void QTextToSpeech::errorOccurred(QTextToSpeech::ErrorReason reason, const QString &errorString)
 
     This signal is emitted after an error occurred and the \l state has been set to
@@ -359,7 +398,14 @@ QTextToSpeech::State QTextToSpeech::state() const
 */
 
 /*!
-    \return the reason why the engine has reported an error
+    \qmlmethod enumeration TextToSpeech::errorReason()
+    \return the reason why the engine has reported an error.
+
+    \sa QTextToSpeech::ErrorReason
+*/
+
+/*!
+    \return the reason why the engine has reported an error.
 
     \sa state errorOccurred()
 */
@@ -372,7 +418,12 @@ QTextToSpeech::ErrorReason QTextToSpeech::errorReason() const
 }
 
 /*!
-    \return the current engine error message
+    \qmlmethod string TextToSpeech::errorString()
+    \return the current engine error message.
+*/
+
+/*!
+    \return the current engine error message.
 
     \sa errorOccurred()
 */
@@ -385,6 +436,24 @@ QString QTextToSpeech::errorString() const
 }
 
 /*!
+    \qmlmethod TextToSpeech::say(string text)
+
+    Starts synthesizing the \a text.
+
+    This function starts sythesizing the speech asynchronously, and reads the text to the
+    default audio output device.
+
+    \note All in-progress readings are stopped before beginning to read the recently
+    synthesized text.
+
+    The current state is available using the \l state property, and is
+    set to \l {QTextToSpeech::Speaking} once the reading starts. When the reading is done,
+    \l state will be set to \l {QTextToSpeech::Ready}.
+
+    \sa stop(), pause(), resume()
+*/
+
+/*!
     Starts synthesizing the \a text.
 
     This function starts sythesizing the speech asynchronously, and reads the text to the
@@ -397,7 +466,7 @@ QString QTextToSpeech::errorString() const
     set to \l Speaking once the reading starts. When the reading is done,
     \l state will be set to \l Ready.
 
-    \sa stop() pause() resume()
+    \sa stop(), pause(), resume()
 */
 void QTextToSpeech::say(const QString &text)
 {
@@ -407,12 +476,23 @@ void QTextToSpeech::say(const QString &text)
 }
 
 /*!
+    \qmlmethod TextToSpeech::stop(BoundaryHint boundaryHint)
+
+    Stops the current reading at \a boundaryHint.
+
+    The reading cannot be resumed. Whether the \a boundaryHint is
+    respected depends on the engine.
+
+    \sa say(), pause(), QTextToSpeech::BoundaryHint
+*/
+
+/*!
     Stops the current reading at \a boundaryHint.
 
     The reading cannot be resumed. Whether the \a boundaryHint is
     respected depends on the engine.
 
-    \sa say() pause()
+    \sa say(), pause()
 */
 void QTextToSpeech::stop(BoundaryHint boundaryHint)
 {
@@ -422,6 +502,16 @@ void QTextToSpeech::stop(BoundaryHint boundaryHint)
 }
 
 /*!
+    \qmlmethod TextToSpeech::pause(BoundaryHint boundaryHint)
+
+    Pauses the current speech at \a boundaryHint.
+
+    Whether the \a boundaryHint is respected depends on the  \l engine.
+
+    \sa resume(), QTextToSpeech::BoundaryHint
+*/
+
+/*!
     Pauses the current speech at \a boundaryHint.
 
     Whether the \a boundaryHint is respected depends on the  \l engine.
@@ -436,6 +526,14 @@ void QTextToSpeech::pause(BoundaryHint boundaryHint)
 }
 
 /*!
+    \qmlmethod TextToSpeech::resume()
+
+    Resume speaking after \l pause() has been called.
+
+    \sa pause()
+*/
+
+/*!
     Resume speaking after \l pause() has been called.
 
     \sa pause()
@@ -448,6 +546,14 @@ void QTextToSpeech::resume()
 }
 
 /*!
+    \qmlproperty double TextToSpeech::pitch
+
+    This property hold the voice pitch, ranging from -1.0 to 1.0.
+
+    The default of 0.0 is the normal speech pitch.
+*/
+
+/*!
     \property QTextToSpeech::pitch
     \brief the voice pitch, ranging from -1.0 to 1.0.
 
@@ -476,6 +582,14 @@ double QTextToSpeech::pitch() const
 }
 
 /*!
+    \qmlproperty double TextToSpeech::rate
+
+    \brief This property holds the current voice rate, ranging from -1.0 to 1.0.
+
+    The default of 0.0 is the normal speech flow.
+*/
+
+/*!
     \property QTextToSpeech::rate
     \brief the current voice rate, ranging from -1.0 to 1.0.
 
@@ -502,6 +616,14 @@ double QTextToSpeech::rate() const
 }
 
 /*!
+    \qmlproperty double TextToSpeech::volume
+
+    \brief This property holds the current volume, ranging from 0.0 to 1.0.
+
+    The default value is the platform's default volume.
+*/
+
+/*!
     \property QTextToSpeech::volume
     \brief the current volume, ranging from 0.0 to 1.0.
 
@@ -530,8 +652,20 @@ double QTextToSpeech::volume() const
 }
 
 /*!
+    \qmlproperty locale TextToSpeech::locale
+
+    \brief This property holds the current locale in use.
+
+    By default, the system locale is used.
+
+    \sa voice
+*/
+
+/*!
     \property QTextToSpeech::locale
-    \brief the current locale in use. By default, the system locale is used.
+    \brief the current locale in use.
+
+    By default, the system locale is used.
 
     On some platforms, changing the locale will update the list of
     \l{availableVoices()}{available voices}, and if the current voice is not
@@ -565,10 +699,13 @@ QLocale QTextToSpeech::locale() const
 }
 
 /*!
-    \return the list of locales that are supported by the active \l engine.
+    \qmlmethod list<Voice> TextToSpeech::availableLocales()
 
-    \note On some platforms these can change, for example,
-    when the backend changes synthesizers.
+    Holds the list of locales that are supported by the active \l engine.
+*/
+
+/*!
+    \return the list of locales that are supported by the active \l engine.
 */
 QList<QLocale> QTextToSpeech::availableLocales() const
 {
@@ -579,6 +716,18 @@ QList<QLocale> QTextToSpeech::availableLocales() const
 }
 
 /*!
+    \qmlproperty Voice TextToSpeech::voice
+
+    \brief This property holds the current locale in use.
+
+    By default, the system locale is used.
+
+    On some platforms, setting the voice changes other voice attributes such
+    as \l locale, \l pitch, and so on. These changes trigger the emission of
+    signals.
+*/
+
+/*!
     \property QTextToSpeech::voice
     \brief the voice that will be used for the speech.
 
@@ -612,6 +761,12 @@ QVoice QTextToSpeech::voice() const
 }
 
 /*!
+    \qmlmethod list<Voice> TextToSpeech::availableVoices()
+
+    Holds the list of voices available for the current \l locale.
+*/
+
+/*!
     \return the list of voices available for the current \l locale.
 
     \note If no locale has been set, the system locale is used.
diff --git a/src/tts/qvoice.cpp b/src/tts/qvoice.cpp
index 0b64d33..7314f52 100644
--- a/src/tts/qvoice.cpp
+++ b/src/tts/qvoice.cpp
@@ -15,6 +15,20 @@ QT_DEFINE_QESDP_SPECIALIZATION_DTOR(QVoicePrivate)
     \class QVoice
     \brief The QVoice class represents a particular voice.
     \inmodule QtTextToSpeech
+    \ingroup qttexttospeech_cpp
+
+    To get a voice that is supported by the current text-to-speech engine,
+    use \l QTextToSpeech::availableVoices().
+*/
+
+/*!
+    \qmltype Voice
+    \inqmlmodule QtTextToSpeech
+    \ingroup texttospeech_qml
+    \brief The Voice type represents a particular voice.
+
+    To get a voice that is supported by the current text-to-speech engine,
+    use \l TextToSpeech::availableVoices().
 */
 
 /*!
@@ -92,7 +106,7 @@ QVoice::QVoice(const QString &name, const QLocale &locale, Gender gender,
 
 /*!
     \internal
-    Compares the \l name, \l gender, and \l age of this voice with \a other.
+    Compares all attributes of this voice with \a other.
     Returns \c true if all of them match.
 */
 bool QVoice::isEqual(const QVoice &other) const noexcept
@@ -102,11 +116,11 @@ bool QVoice::isEqual(const QVoice &other) const noexcept
     if (!d || !other.d)
         return false;
 
-    return d->name == other.d->name
+    return d->data == other.d->data
+        && d->name == other.d->name
         && d->locale == other.d->locale
         && d->gender == other.d->gender
-        && d->age == other.d->age
-        && d->data == other.d->data;
+        && d->age == other.d->age;
 }
 
 /*!
@@ -123,6 +137,11 @@ bool QVoice::isEqual(const QVoice &other) const noexcept
 */
 
 /*!
+    \qmlproperty string Voice::name
+    \brief This property holds the name of the voice.
+*/
+
+/*!
     \property QVoice::name
     \brief the name of a voice
 */
@@ -132,6 +151,14 @@ QString QVoice::name() const
 }
 
 /*!
+    \qmlproperty locale Voice::locale
+    \brief This property holds the locale of the voice.
+
+    The locale includes the language and the territory (i.e. accent or dialect)
+    of the voice.
+*/
+
+/*!
     \property QVoice::locale
     \brief the locale of the voice
     \since 6.4
@@ -145,6 +172,13 @@ QLocale QVoice::locale() const
 }
 
 /*!
+    \qmlproperty enumeration Voice::gender
+    \brief This property holds the gender of the voice.
+
+    \sa QVoice::Gender
+*/
+
+/*!
     \property QVoice::gender
     \brief the gender of a voice
 */
@@ -154,6 +188,13 @@ QVoice::Gender QVoice::gender() const
 }
 
 /*!
+    \qmlproperty enumeration Voice::age
+    \brief This property holds the age of the voice.
+
+    \sa QVoice::Age
+*/
+
+/*!
     \property QVoice::age
     \brief the age of a voice
 */