Doc: Fix documentation warningsv5.11.0-beta4

Use complete function signatures for \fn commands (including template
specifiers) as Clang parser now reads them.

Convert internal class documentation comments to standard C-style
comments.

Change-Id: Ie67eb054171139db12f7e74d077b7dc8453582df
Reviewed-by: Martin Smith <martin.smith@qt.io>

6 files changed, 39 insertions, 43 deletions

diff --git a/src/script/api/qscriptengine.cpp b/src/script/api/qscriptengine.cpp
index 3719cdf..c5f437b 100644
--- a/src/script/api/qscriptengine.cpp
+++ b/src/script/api/qscriptengine.cpp
@@ -3869,7 +3869,7 @@ QStringList QScriptEngine::importedExtensions() const
     return lst;
 }
 
-/*! \fn QScriptValue QScriptEngine::toScriptValue(const T &value)
+/*! \fn template <typename T> QScriptValue QScriptEngine::toScriptValue(const T &value)
 
     Creates a QScriptValue with the given \a value.
 
@@ -3885,7 +3885,7 @@ QStringList QScriptEngine::importedExtensions() const
     \sa fromScriptValue(), qScriptRegisterMetaType()
 */
 
-/*! \fn T QScriptEngine::fromScriptValue(const QScriptValue &value)
+/*! \fn template <typename T> T QScriptEngine::fromScriptValue(const QScriptValue &value)
 
     Returns the given \a value converted to the template type \c{T}.
 
@@ -3899,7 +3899,7 @@ QStringList QScriptEngine::importedExtensions() const
 */
 
 /*!
-    \fn QScriptValue qScriptValueFromValue(QScriptEngine *engine, const T &value)
+    \fn template <typename T> QScriptValue qScriptValueFromValue(QScriptEngine *engine, const T &value)
     \since 4.3
     \relates QScriptEngine
     \obsolete
@@ -3917,7 +3917,7 @@ QStringList QScriptEngine::importedExtensions() const
 */
 
 /*!
-    \fn T qScriptValueToValue(const QScriptValue &value)
+    \fn template <typename T> T qScriptValueToValue(const QScriptValue &value)
     \since 4.3
     \relates QScriptEngine
     \obsolete
@@ -3934,7 +3934,7 @@ QStringList QScriptEngine::importedExtensions() const
 */
 
 /*!
-    \fn QScriptValue qScriptValueFromSequence(QScriptEngine *engine, const Container &container)
+    \fn template <class Container> QScriptValue qScriptValueFromSequence(QScriptEngine *engine, const Container &container)
     \since 4.3
     \relates QScriptEngine
 
@@ -3953,7 +3953,7 @@ QStringList QScriptEngine::importedExtensions() const
 */
 
 /*!
-    \fn void qScriptValueToSequence(const QScriptValue &value, Container &container)
+    \fn template <class Container> void qScriptValueToSequence(const QScriptValue &value, Container &container)
     \since 4.3
     \relates QScriptEngine
 
@@ -3974,7 +3974,7 @@ QStringList QScriptEngine::importedExtensions() const
 */
 
 /*!
-    \fn T qscriptvalue_cast(const QScriptValue &value)
+    \fn template <typename T> T qscriptvalue_cast(const QScriptValue &value)
     \since 4.3
     \relates QScriptValue
 
@@ -3983,14 +3983,15 @@ QStringList QScriptEngine::importedExtensions() const
     \sa qScriptRegisterMetaType(), QScriptEngine::toScriptValue()
 */
 
-/*! \fn int qScriptRegisterMetaType(
-            QScriptEngine *engine,
+/*! \fn template<typename T> int qScriptRegisterMetaType(
+            QScriptEngine *eng,
             QScriptValue (*toScriptValue)(QScriptEngine *, const T &t),
             void (*fromScriptValue)(const QScriptValue &, T &t),
-            const QScriptValue &prototype = QScriptValue())
+            const QScriptValue &prototype, T *)
+
     \relates QScriptEngine
 
-    Registers the type \c{T} in the given \a engine. \a toScriptValue must
+    Registers the type \c{T} in the given \a eng. \a toScriptValue must
     be a function that will convert from a value of type \c{T} to a
     QScriptValue, and \a fromScriptValue a function that does the
     opposite. \a prototype, if valid, is the prototype that's set on
@@ -4071,9 +4072,11 @@ QStringList QScriptEngine::importedExtensions() const
     QScriptEngine::AutoOwnership ownership.
 */
 
-/*! \fn int qScriptRegisterSequenceMetaType(
+/*!
+    \fn template<typename T> int qScriptRegisterSequenceMetaType(
             QScriptEngine *engine,
-            const QScriptValue &prototype = QScriptValue())
+            const QScriptValue &prototype, T *)
+
     \relates QScriptEngine
 
     Registers the sequence type \c{T} in the given \a engine. This
diff --git a/src/script/api/qscriptengine.h b/src/script/api/qscriptengine.h
index c7bda46..04f678d 100644
--- a/src/script/api/qscriptengine.h
+++ b/src/script/api/qscriptengine.h
@@ -378,11 +378,8 @@ int qScriptRegisterMetaType(
     QScriptEngine *eng,
     QScriptValue (*toScriptValue)(QScriptEngine *, const T &t),
     void (*fromScriptValue)(const QScriptValue &, T &t),
-    const QScriptValue &prototype = QScriptValue()
-#ifndef qdoc
-    , T * /* dummy */ = 0
-#endif
-)
+    const QScriptValue &prototype = QScriptValue(),
+    T * /* dummy */ = 0)
 {
     const int id = qRegisterMetaType<T>(); // make sure it's registered
 
@@ -420,11 +417,8 @@ void qScriptValueToSequence(const QScriptValue &value, Container &cont)
 template<typename T>
 int qScriptRegisterSequenceMetaType(
     QScriptEngine *engine,
-    const QScriptValue &prototype = QScriptValue()
-#ifndef qdoc
-    , T * /* dummy */ = 0
-#endif
-)
+    const QScriptValue &prototype = QScriptValue(),
+    T * /* dummy */ = 0)
 {
     return qScriptRegisterMetaType<T>(engine, qScriptValueFromSequence,
                                       qScriptValueToSequence, prototype);
diff --git a/src/script/api/qscriptengineagent.cpp b/src/script/api/qscriptengineagent.cpp
index 12b8b53..ac9a016 100644
--- a/src/script/api/qscriptengineagent.cpp
+++ b/src/script/api/qscriptengineagent.cpp
@@ -440,7 +440,7 @@ void QScriptEngineAgent::exceptionCatch(qint64 scriptId,
 }
 
 #if 0
-/*!
+/*
   This function is called when a property of the given \a object has
   been added, changed or removed.
 
diff --git a/src/scripttools/debugging/qscriptdebugger.cpp b/src/scripttools/debugging/qscriptdebugger.cpp
index 381d108..5f589d4 100644
--- a/src/scripttools/debugging/qscriptdebugger.cpp
+++ b/src/scripttools/debugging/qscriptdebugger.cpp
@@ -135,7 +135,6 @@ static bool scriptDebuggerEventCallback(void **data)
   \brief The QScriptDebugger class provides a Qt Script debugger.
 
   \ingroup script
-
 */
 
 class QScriptDebuggerPrivate
@@ -335,7 +334,7 @@ QPixmap QScriptDebuggerPrivate::pixmap(const QString &path)
     return QPixmap(prefix + path);
 }
 
-/*!
+/*
   \reimp
 */
 int QScriptDebuggerPrivate::scheduleJob(QScriptDebuggerJob *job)
@@ -350,7 +349,7 @@ int QScriptDebuggerPrivate::scheduleJob(QScriptDebuggerJob *job)
     return id;
 }
 
-/*!
+/*
   \reimp
 */
 void QScriptDebuggerPrivate::finishJob(QScriptDebuggerJob *job)
@@ -363,7 +362,7 @@ void QScriptDebuggerPrivate::finishJob(QScriptDebuggerJob *job)
     maybeStartNewJob();
 }
 
-/*!
+/*
   \reimp
 */
 void QScriptDebuggerPrivate::hibernateUntilEvaluateFinished(QScriptDebuggerJob *job)
@@ -373,7 +372,7 @@ void QScriptDebuggerPrivate::hibernateUntilEvaluateFinished(QScriptDebuggerJob *
     activeJobHibernating = true;
 }
 
-/*!
+/*
   Starts a new job if appropriate.
 */
 void QScriptDebuggerPrivate::maybeStartNewJob()
@@ -384,7 +383,7 @@ void QScriptDebuggerPrivate::maybeStartNewJob()
     activeJob->start();
 }
 
-/*!
+/*
   \reimp
 */
 int QScriptDebuggerPrivate::scheduleCommand(
@@ -405,7 +404,7 @@ int QScriptDebuggerPrivate::scheduleCommand(
     return id;
 }
 
-/*!
+/*
   \reimp
 */
 void QScriptDebuggerPrivate::handleResponse(
@@ -478,7 +477,7 @@ void QScriptDebuggerPrivate::handleResponse(
         realHandler->handleResponse(response, commandId);
 }
 
-/*!
+/*
   \reimp
 
   Handles a debugger event from the frontend.
@@ -668,7 +667,7 @@ private:
     QStringList m_path;
 };
 
-/*!
+/*
   \reimp
 */
 void QScriptDebuggerPrivate::showToolTip(const QPoint &pos, int frameIndex,
@@ -684,7 +683,7 @@ void QScriptDebuggerPrivate::showToolTip(const QPoint &pos, int frameIndex,
     scheduleJob(job);
 }
 
-/*!
+/*
   \reimp
 */
 QScriptCompletionTaskInterface *QScriptDebuggerPrivate::createCompletionTask(
@@ -695,7 +694,7 @@ QScriptCompletionTaskInterface *QScriptDebuggerPrivate::createCompletionTask(
         (options & QScriptCompletionProviderInterface::ConsoleCommandCompletion) ? console : 0);
 }
 
-/*!
+/*
   Slot called when a line has been entered in the console widget.
 */
 void QScriptDebuggerPrivate::_q_onLineEntered(const QString &contents)
@@ -710,7 +709,7 @@ void QScriptDebuggerPrivate::_q_onLineEntered(const QString &contents)
     }
 }
 
-/*!
+/*
   Slot called when the current index has changed in the stack widget.
 */
 void QScriptDebuggerPrivate::_q_onCurrentFrameChanged(int frameIndex)
@@ -719,7 +718,7 @@ void QScriptDebuggerPrivate::_q_onCurrentFrameChanged(int frameIndex)
     selectScriptForFrame(frameIndex);
 }
 
-/*!
+/*
   Slot called when the current script has changed in the scripts widget.
 */
 void QScriptDebuggerPrivate::_q_onCurrentScriptChanged(qint64 scriptId)
diff --git a/src/scripttools/debugging/qscriptdebuggerconsole.cpp b/src/scripttools/debugging/qscriptdebuggerconsole.cpp
index 297fa65..9968411 100644
--- a/src/scripttools/debugging/qscriptdebuggerconsole.cpp
+++ b/src/scripttools/debugging/qscriptdebuggerconsole.cpp
@@ -323,7 +323,7 @@ QScriptDebuggerConsolePrivate::~QScriptDebuggerConsolePrivate()
     delete commandEngine;
 }
 
-/*!
+/*
   Loads command definitions from scripts located in the given \a scriptsPath.
 */
 void QScriptDebuggerConsolePrivate::loadScriptedCommands(
@@ -351,7 +351,7 @@ void QScriptDebuggerConsolePrivate::loadScriptedCommands(
 }
 
 
-/*!
+/*
   Creates a job that will execute the given debugger \a command.
   Returns the new job, or 0 if the command is undefined.
 */
diff --git a/src/scripttools/debugging/qscriptenginedebuggerfrontend.cpp b/src/scripttools/debugging/qscriptenginedebuggerfrontend.cpp
index 78c56fa..e038a67 100644
--- a/src/scripttools/debugging/qscriptenginedebuggerfrontend.cpp
+++ b/src/scripttools/debugging/qscriptenginedebuggerfrontend.cpp
@@ -162,7 +162,7 @@ QScriptEngineDebuggerBackendPrivate::~QScriptEngineDebuggerBackendPrivate()
     }
 }
 
-/*!
+/*
   \reimp
 */
 bool QScriptEngineDebuggerBackendPrivate::event(QEvent *e)
@@ -203,7 +203,7 @@ void QScriptEngineDebuggerBackend::processCommand(int id, const QScriptDebuggerC
         d->postEvent(new QScriptDebuggerCommandEvent(id, command));
 }
 
-/*!
+/*
   \reimp
 */
 void QScriptEngineDebuggerBackend::event(const QScriptDebuggerEvent &event)
@@ -230,7 +230,7 @@ void QScriptEngineDebuggerBackend::event(const QScriptDebuggerEvent &event)
     doPendingEvaluate(/*postEvent=*/false);
 }
 
-/*!
+/*
   \reimp
 */
 void QScriptEngineDebuggerBackend::resume()
@@ -260,7 +260,7 @@ void QScriptEngineDebuggerFrontendPrivate::postCommandFinished(
     postEvent(new QScriptDebuggerCommandFinishedEvent(id, response));
 }
 
-/*!
+/*
   \reimp
 */
 bool QScriptEngineDebuggerFrontendPrivate::event(QEvent *e)