Doc: Resolve all documentation warnings

QDoc in Qt 5.11 uses Clang to parse the C++ source for documentation.
for this, Clang needs a module header which is not available for
Qt Virtual Keyboard - construct a custom one for documentation builds
and fix all remaining documentation warnings; \fn command syntax and
one linking issue.

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

5 files changed, 62 insertions, 18 deletions

diff --git a/src/virtualkeyboard/abstractinputmethod.cpp b/src/virtualkeyboard/abstractinputmethod.cpp
index 42c4f302..dece2c7f 100644
--- a/src/virtualkeyboard/abstractinputmethod.cpp
+++ b/src/virtualkeyboard/abstractinputmethod.cpp
@@ -233,27 +233,27 @@ bool AbstractInputMethod::reselect(int cursorPosition, const InputEngine::Resele
 }
 
 /*!
-    \fn QList<InputEngine::InputMode> AbstractInputMethod::inputModes(const QString& locale)
+    \fn QList<QtVirtualKeyboard::InputEngine::InputMode> QtVirtualKeyboard::AbstractInputMethod::inputModes(const QString& locale)
 
     Returns the list of input modes for \a locale.
 */
 
 /*!
-    \fn bool AbstractInputMethod::setInputMode(const QString& locale, InputEngine::InputMode inputMode)
+    \fn bool QtVirtualKeyboard::AbstractInputMethod::setInputMode(const QString& locale, InputEngine::InputMode inputMode)
 
     Sets the \a inputMode and \a locale for this input method. Returns \c true
     if successful.
 */
 
 /*!
-    \fn bool AbstractInputMethod::setTextCase(InputEngine::TextCase textCase)
+    \fn bool QtVirtualKeyboard::AbstractInputMethod::setTextCase(InputEngine::TextCase textCase)
 
     Updates the \a textCase for this input method. The method returns \c true
     if successful.
 */
 
 /*!
-    \fn bool AbstractInputMethod::keyEvent(Qt::Key key, const QString& text, Qt::KeyboardModifiers modifiers)
+    \fn bool QtVirtualKeyboard::AbstractInputMethod::keyEvent(Qt::Key key, const QString& text, Qt::KeyboardModifiers modifiers)
 
     The purpose of this method is to handle the key events generated by the the
     input engine.
@@ -269,7 +269,7 @@ bool AbstractInputMethod::reselect(int cursorPosition, const InputEngine::Resele
 */
 
 /*!
-    \fn QList<SelectionListModel::Type> AbstractInputMethod::selectionLists()
+    \fn QList<SelectionListModel::Type> QtVirtualKeyboard::AbstractInputMethod::selectionLists()
 
     Returns the list of selection lists used by this input method.
 
@@ -284,13 +284,13 @@ bool AbstractInputMethod::reselect(int cursorPosition, const InputEngine::Resele
 */
 
 /*!
-    \fn int AbstractInputMethod::selectionListItemCount(SelectionListModel::Type type)
+    \fn int QtVirtualKeyboard::AbstractInputMethod::selectionListItemCount(SelectionListModel::Type type)
 
     Returns the number of items in the selection list identified by \a type.
 */
 
 /*!
-    \fn QVariant AbstractInputMethod::selectionListData(SelectionListModel::Type type, int index, int role)
+    \fn QVariant QtVirtualKeyboard::AbstractInputMethod::selectionListData(SelectionListModel::Type type, int index, int role)
 
     Returns item data for the selection list identified by \a type. The \a role
     parameter specifies which data is requested. The \a index parameter is a
@@ -298,14 +298,14 @@ bool AbstractInputMethod::reselect(int cursorPosition, const InputEngine::Resele
 */
 
 /*!
-    \fn void AbstractInputMethod::selectionListItemSelected(SelectionListModel::Type type, int index)
+    \fn void QtVirtualKeyboard::AbstractInputMethod::selectionListItemSelected(SelectionListModel::Type type, int index)
 
     This method is called when an item at \a index has been selected by the
     user. The selection list is identified by the \a type parameter.
 */
 
 /*!
-    \fn void AbstractInputMethod::selectionListChanged(int type)
+    \fn void QtVirtualKeyboard::AbstractInputMethod::selectionListChanged(int type)
 
     The input method emits this signal when the contents of the selection list
     has changed. The \a type parameter specifies which selection list has
@@ -313,14 +313,14 @@ bool AbstractInputMethod::reselect(int cursorPosition, const InputEngine::Resele
 */
 
 /*!
-    \fn void AbstractInputMethod::selectionListActiveItemChanged(int type, int index)
+    \fn void QtVirtualKeyboard::AbstractInputMethod::selectionListActiveItemChanged(int type, int index)
 
     The input method emits this signal when the current \a index has changed
     in the selection list identified by \a type.
 */
 
 /*!
-    \fn void AbstractInputMethod::selectionListsChanged()
+    \fn void QtVirtualKeyboard::AbstractInputMethod::selectionListsChanged()
     \since QtQuick.VirtualKeyboard 2.2
 
     The input method emits this signal when the selection list types have
diff --git a/src/virtualkeyboard/abstractinputpanel.cpp b/src/virtualkeyboard/abstractinputpanel.cpp
index 564582fb..41c72d58 100644
--- a/src/virtualkeyboard/abstractinputpanel.cpp
+++ b/src/virtualkeyboard/abstractinputpanel.cpp
@@ -77,19 +77,19 @@ AbstractInputPanel::~AbstractInputPanel()
 }
 
 /*!
-    \fn void AbstractInputPanel::show() = 0
+    \fn void QtVirtualKeyboard::AbstractInputPanel::show() = 0
 
     Shows the input panel.
 */
 
 /*!
-    \fn void AbstractInputPanel::hide() = 0
+    \fn void QtVirtualKeyboard::AbstractInputPanel::hide() = 0
 
     Hides the input panel.
 */
 
 /*!
-    \fn bool AbstractInputPanel::isVisible() const = 0
+    \fn bool QtVirtualKeyboard::AbstractInputPanel::isVisible() const = 0
 
     Returns \c true if the input panel is currently visible.
 */
@@ -112,7 +112,7 @@ void AbstractInputPanel::createView()
 }
 
 /*!
-    \fn void AbstractInputPanel::destroyView()
+    \fn void QtVirtualKeyboard::AbstractInputPanel::destroyView()
 
     Destroys the view of the input panel.
 */
diff --git a/src/virtualkeyboard/content/InputPanel.qml b/src/virtualkeyboard/content/InputPanel.qml
index 3f88bb30..ec771c4e 100644
--- a/src/virtualkeyboard/content/InputPanel.qml
+++ b/src/virtualkeyboard/content/InputPanel.qml
@@ -84,9 +84,10 @@ Item {
         the built-in language popup in the virtual keyboard.
 
         The \a localeList parameter contains a list of locale names to choose
-        from. To get more information about a particular language, use the \l Qt.locale()
-        function. The \a currentIndex is the index of current locale in the
-        \a localeList. This item should be highlighted as the current item in the UI.
+        from. To get more information about a particular language, use the
+        \l {QtQml::Qt::locale()}{Qt.locale()} function. The \a currentIndex
+        is the index of current locale in the \a localeList. This item should
+        be highlighted as the current item in the UI.
 
         To select a new language, use the \l {VirtualKeyboardSettings::locale}
         {VirtualKeyboardSettings.locale} property.
diff --git a/src/virtualkeyboard/doc/QtVirtualKeyboard_pch.h b/src/virtualkeyboard/doc/QtVirtualKeyboard_pch.h
new file mode 100644
index 00000000..298f0f60
--- /dev/null
+++ b/src/virtualkeyboard/doc/QtVirtualKeyboard_pch.h
@@ -0,0 +1,37 @@
+/****************************************************************************
+**
+** Copyright (C) 2018 The Qt Company Ltd.
+** Contact: https://www.qt.io/licensing/
+**
+** This file is part of the Qt Virtual Keyboard module of the Qt Toolkit.
+**
+** $QT_BEGIN_LICENSE:GPL$
+** Commercial License Usage
+** Licensees holding valid commercial Qt licenses may use this file in
+** accordance with the commercial license agreement provided with the
+** Software or, alternatively, in accordance with the terms contained in
+** a written agreement between you and The Qt Company. For licensing terms
+** and conditions see https://www.qt.io/terms-conditions. For further
+** information use the contact form at https://www.qt.io/contact-us.
+**
+** GNU General Public License Usage
+** Alternatively, this file may be used under the terms of the GNU
+** General Public License version 3 or (at your option) any later version
+** approved by the KDE Free Qt Foundation. The licenses are as published by
+** the Free Software Foundation and appearing in the file LICENSE.GPL3
+** included in the packaging of this file. Please review the following
+** information to ensure the GNU General Public License requirements will
+** be met: https://www.gnu.org/licenses/gpl-3.0.html.
+**
+** $QT_END_LICENSE$
+**
+****************************************************************************/
+
+#ifdef Q_CLANG_QDOC
+#include "abstractinputmethod.h"
+#include "abstractinputpanel.h"
+#include "inputcontext.h"
+#include "inputengine.h"
+#include "selectionlistmodel.h"
+#include "shifthandler.h"
+#endif // Q_CLANG_QDOC
diff --git a/src/virtualkeyboard/doc/qtvirtualkeyboard.qdocconf b/src/virtualkeyboard/doc/qtvirtualkeyboard.qdocconf
index fbb0d465..71697785 100644
--- a/src/virtualkeyboard/doc/qtvirtualkeyboard.qdocconf
+++ b/src/virtualkeyboard/doc/qtvirtualkeyboard.qdocconf
@@ -4,6 +4,12 @@ project = QtVirtualKeyboard
 description = Qt Virtual Keyboard
 version = $QT_VERSION
 
+# Custom module header passed to clang
+moduleheader = QtVirtualKeyboard_pch.h
+
+# Additional include paths passed to clang
+includepaths = -I .
+
 headerdirs  += ..
 sourcedirs  += ..
 excludedirs += ../content/layouts \