From b113bca742e01d3771f4f8ee0c5dc5ea5a97816e Mon Sep 17 00:00:00 2001 From: Topi Reinio Date: Wed, 25 Apr 2018 12:38:56 +0200 Subject: Doc: Resolve documentation warnings - 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 Reviewed-by: Martin Smith --- src/doc/QtSpeechDoc | 1 + src/doc/qtspeech.qdocconf | 6 +++ src/tts/qtexttospeechengine.cpp | 89 +++++++++++++++++++++-------------------- src/tts/qvoice.cpp | 47 +++++++++++++++++----- 4 files changed, 90 insertions(+), 53 deletions(-) create mode 100644 src/doc/QtSpeechDoc 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 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 QTextToSpeechPluginEngine::availableLocales() const +/*! \fn QVector QTextToSpeechEngine::availableLocales() const - Implementation of \l QTextToSpeech::availableLocales() + Implementation of \l QTextToSpeech::availableLocales(). */ -/*! \fn QVector QTextToSpeechPluginEngine::availableVoices() const +/*! \fn QVector 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) { -- cgit v1.2.3