Doc: Resolve documentation warningsv5.11.0-rc2v5.11.0-rc1v5.11.0

- Add missing enumeration docs to QVoice.
- Fix the name of the QTextToSpeechEngine class and fix missing
  parameter documentation.
- Add custom module header and include paths for Clang-QDoc.
- Fix minor formatting issues.

Task-number: QTBUG-67790
Change-Id: I18e9af9e9f47afe0b76ca973e0b304af5fe599df
Reviewed-by: Paul Wicking <paul.wicking@qt.io>
Reviewed-by: Martin Smith <martin.smith@qt.io>

4 files changed, 90 insertions, 53 deletions

diff --git a/src/doc/QtSpeechDoc b/src/doc/QtSpeechDoc
new file mode 100644
index 0000000..73ff578
--- /dev/null
+++ b/src/doc/QtSpeechDoc
@@ -0,0 +1 @@
+#include <QtTextToSpeech/QtTextToSpeech>
diff --git a/src/doc/qtspeech.qdocconf b/src/doc/qtspeech.qdocconf
index 8fd2d73..4259272 100644
--- a/src/doc/qtspeech.qdocconf
+++ b/src/doc/qtspeech.qdocconf
@@ -12,6 +12,12 @@ imagedirs += images
 exampledirs += \
               ../../examples/speech
 
+moduleheader = QtSpeechDoc
+
+includepaths = -I . \
+               -I $QT_INSTALL_HEADERS \
+               -I $QT_INSTALL_HEADERS/QtCore
+
 examplesinstallpath = speech
 
 depends += qtcore qtdoc
diff --git a/src/tts/qtexttospeechengine.cpp b/src/tts/qtexttospeechengine.cpp
index 5d87224..a107fc2 100644
--- a/src/tts/qtexttospeechengine.cpp
+++ b/src/tts/qtexttospeechengine.cpp
@@ -42,119 +42,120 @@ QT_BEGIN_NAMESPACE
 
 
 /*!
-  \class QTextToSpeechPluginEngine
+  \class QTextToSpeechEngine
   \inmodule QtSpeech
-  \brief The QTextToSpeechPluginEngine class is the base for text-to-speech engine integrations.
+  \brief The QTextToSpeechEngine class is the base for text-to-speech engine integrations.
 
-  An engine implementation should derive from QTextToSpeechPluginEngine and implement all
-  the pure virtual methods.
+  An engine implementation must derive from QTextToSpeechEngine and implement all
+  its pure virtual methods.
 */
 
-/*! \fn QVector<QLocale> QTextToSpeechPluginEngine::availableLocales() const
+/*! \fn QVector<QLocale> QTextToSpeechEngine::availableLocales() const
 
-  Implementation of \l QTextToSpeech::availableLocales()
+  Implementation of \l QTextToSpeech::availableLocales().
 */
 
-/*! \fn QVector<QVoice> QTextToSpeechPluginEngine::availableVoices() const
+/*! \fn QVector<QVoice> QTextToSpeechEngine::availableVoices() const
 
-  Implementation of \l QTextToSpeech::availableVoices()
+  Implementation of \l QTextToSpeech::availableVoices().
 */
 
-/*! \fn void QTextToSpeechPluginEngine::say(const QString &text)
+/*! \fn void QTextToSpeechEngine::say(const QString &text)
 
-  Implementation of \l QTextToSpeech::say()
+  Implementation of \l {QTextToSpeech::say()}{QTextToSpeech::say}(\a text).
 */
 
-/*! \fn void QTextToSpeechPluginEngine::stop()
+/*! \fn void QTextToSpeechEngine::stop()
 
-  Implementation of \l QTextToSpeech::stop()
+  Implementation of \l QTextToSpeech::stop().
 */
 
-/*! \fn void QTextToSpeechPluginEngine::pause()
+/*! \fn void QTextToSpeechEngine::pause()
 
-  Implementation of \l QTextToSpeech::pause()
+  Implementation of \l QTextToSpeech::pause().
 */
 
-/*! \fn void QTextToSpeechPluginEngine::resume()
+/*! \fn void QTextToSpeechEngine::resume()
 
-  Implementation of \l QTextToSpeech::resume()
+  Implementation of \l QTextToSpeech::resume().
 */
 
-/*! \fn void QTextToSpeechPluginEngine::rate() const
+/*! \fn void QTextToSpeechEngine::rate() const
 
-  Implementation of \l QTextToSpeech::rate()
+  Implementation of \l QTextToSpeech::rate().
 */
 
-/*! \fn bool QTextToSpeechPluginEngine::setRate(double rate)
+/*! \fn bool QTextToSpeechEngine::setRate(double rate)
 
-  Implementation of \l QTextToSpeech::setRate().
+  Implementation of \l {QTextToSpeech::setRate()}{QTextToSpeech::setRate}(\a rate).
 
   Return \c true if the operation was successful.
 */
 
-/*! \fn void QTextToSpeechPluginEngine::pitch() const
+/*! \fn void QTextToSpeechEngine::pitch() const
 
-  Implementation of \l QTextToSpeech::pitch()
+  Implementation of \l QTextToSpeech::pitch().
 */
 
-/*! \fn bool QTextToSpeechPluginEngine::setPitch(double pitch)
+/*! \fn bool QTextToSpeechEngine::setPitch(double pitch)
 
-  Implementation of \l QTextToSpeech::setPitch()
+  Implementation of \l {QTextToSpeech::setPitch()}{QTextToSpeech::setPitch}(\a pitch).
 
   Return \c true if the operation was successful.
 */
 
-/*! \fn QLocale QTextToSpeechPluginEngine::locale() const
+/*! \fn QLocale QTextToSpeechEngine::locale() const
 
-  Implementation of \l QTextToSpeech::locale()
+  Implementation of QTextToSpeech::locale().
 */
 
-/*! \fn bool QTextToSpeechPluginEngine::setLocale(const QLocale &locale)
+/*! \fn bool QTextToSpeechEngine::setLocale(const QLocale &locale)
 
-  Implementation of \l QTextToSpeech::setLocale()
+  Implementation \l {QTextToSpeech::setLocale()}{QTextToSpeech::setLocale}(\a locale).
 
   Return \c true if the operation was successful. In this case, the
-  current voice (returned by \l voice()) should also have been updated
-  to a valid new value.
+  current voice (as returned by voice()) should also be updated to a
+  new, valid value.
 */
 
-/*! \fn void QTextToSpeechPluginEngine::volume() const
+/*! \fn double QTextToSpeechEngine::volume() const
 
-  Implementation of \l QTextToSpeech::volume()
+  Implementation of QTextToSpeech::volume().
 */
 
-/*! \fn bool QTextToSpeechPluginEngine::setVolume(int volume)
+/*! \fn bool QTextToSpeechEngine::setVolume(double volume)
 
-  Implementation of \l QTextToSpeech::setVolume()
+  Implementation of \l {QTextToSpeech::setVolume()}{QTextToSpeech::setVolume}(\a volume).
 
   Return \c true if the operation was successful.
 */
 
-/*! \fn QVoice QTextToSpeechPluginEngine::voice() const
+/*! \fn QVoice QTextToSpeechEngine::voice() const
 
-  Implementation of \l QTextToSpeech::voice()
+  Implementation of \l QTextToSpeech::voice().
 */
 
-/*! \fn bool QTextToSpeechPluginEngine::setVoice(const QVoice &voice)
+/*! \fn bool QTextToSpeechEngine::setVoice(const QVoice &voice)
 
-  Implementation of \l QTextToSpeech::setVoice()
+  Implementation of \l {QTextToSpeech::setVoice()}{QTextToSpeech::setVoice}(\a voice).
 
   Return \c true if the operation was successful.
 */
 
-/*! \fn QTextToSpeech::State QTextToSpeechPluginEngine::state() const
+/*! \fn QTextToSpeech::State QTextToSpeechEngine::state() const
 
-  Implementation of \l QTextToSpeech::state()
+  Implementation of QTextToSpeech::state().
 */
 
-/*! \fn void QTextToSpeechPluginEngine::stateChanged(QTextToSpeech::State state)
+/*! \fn void QTextToSpeechEngine::stateChanged(QTextToSpeech::State state)
 
-  Emitted when the text-to-speech engine state has changed.
-  This signal is connected to signal QTextToSpeech::stateChanged().
+  Emitted when the text-to-speech engine \a state has changed.
+
+  This signal is connected to QTextToSpeech::stateChanged() signal.
 */
 
 /*!
-  Constructs the text-to-speech engine base class.
+  Constructs the text-to-speech engine base class with \a parent.
 */
 QTextToSpeechEngine::QTextToSpeechEngine(QObject *parent):
     QObject(parent)
diff --git a/src/tts/qvoice.cpp b/src/tts/qvoice.cpp
index 030d621..2c19aff 100644
--- a/src/tts/qvoice.cpp
+++ b/src/tts/qvoice.cpp
@@ -44,10 +44,31 @@ QT_BEGIN_NAMESPACE
 
 /*!
   \class QVoice
-  \brief The QVoice class allows to set and retrieve values of a particular voice
+  \brief The QVoice class allows to set and retrieve values of a particular voice.
   \inmodule QtSpeech
 */
 
+/*!
+    \enum QVoice::Age
+
+    The age of a voice.
+
+    \value Child    Voice of a child
+    \value Teenager Voice of a teenager
+    \value Adult    Voice of an adult
+    \value Senior   Voice of a senior
+    \value Other    Voice of unknown age
+*/
+
+/*!
+    \enum QVoice::Gender
+
+    The gender of a voice.
+
+    \value Male    Voice of a male
+    \value Female  Voice of a female
+    \value Unknown Voice of unknown gender
+*/
 
 QVoice::QVoice()
 {
@@ -76,6 +97,10 @@ void QVoice::operator=(const QVoice &other)
     d->data = other.d->data;
 }
 
+/*!
+    Compares the \l name, \l gender, and \l age of this voice with \l other.
+    Returns \c true if all of them match.
+*/
 bool QVoice::operator==(const QVoice &other)
 {
     if (d->name != other.d->name ||
@@ -86,13 +111,17 @@ bool QVoice::operator==(const QVoice &other)
     return true;
 }
 
+/*!
+    Compares the \l name, \l gender, and \l age of this voice with \l other.
+    Returns \c true if they are not identical.
+*/
 bool QVoice::operator!=(const QVoice &other)
 {
     return !operator==(other);
 }
 
 /*!
-   Assign a \a name to a voice
+   Assign a \a name to a voice.
 */
 void QVoice::setName(const QString &name)
 {
@@ -100,7 +129,7 @@ void QVoice::setName(const QString &name)
 }
 
 /*!
-   Assign a \a gender to a voice
+   Assign a \a gender to a voice.
 */
 void QVoice::setGender(Gender gender)
 {
@@ -108,7 +137,7 @@ void QVoice::setGender(Gender gender)
 }
 
 /*!
-   Set the \a age property
+   Set the \a age property.
 */
 void QVoice::setAge(Age age)
 {
@@ -121,7 +150,7 @@ void QVoice::setData(const QVariant &data)
 }
 
 /*!
-   Returns the name of a voice
+   Returns the name of a voice.
 */
 QString QVoice::name() const
 {
@@ -129,7 +158,7 @@ QString QVoice::name() const
 }
 
 /*!
-   Returns the age of a voice
+   Returns the age of a voice.
 */
 QVoice::Age QVoice::age() const
 {
@@ -137,7 +166,7 @@ QVoice::Age QVoice::age() const
 }
 
 /*!
-   Returns the gender of a voice
+   Returns the gender of a voice.
 */
 QVoice::Gender QVoice::gender() const
 {
@@ -150,7 +179,7 @@ QVariant QVoice::data() const
 }
 
 /*!̈́
-   Returns the \a gender name of a voice
+   Returns the \a gender name of a voice.
 */
 QString QVoice::genderName(QVoice::Gender gender)
 {
@@ -171,7 +200,7 @@ QString QVoice::genderName(QVoice::Gender gender)
 }
 
 /*!
-   Returns the \a age class of a voice
+   Returns a string representing the \a age class of a voice.
 */
 QString QVoice::ageName(QVoice::Age age)
 {