ivigenerator: Generate documentation for the QML module singleton

This includes the generation of a module_qml_enum.qdocinc file which
contains the QML documentation of the enum. The qdoc include
command is used in all functions and properties where the enum is
used.

Fixes: AUTOSUITE-741
Change-Id: I095147acd20910c8d7d5b85d95bee6c6e4bd3dd3
Reviewed-by: Robert Griebl <robert.griebl@pelagicore.com>

5 files changed, 129 insertions, 6 deletions

diff --git a/src/tools/ivigenerator/templates_frontend/interface.cpp.tpl b/src/tools/ivigenerator/templates_frontend/interface.cpp.tpl
index 04b8d25..3c99e3b 100644
--- a/src/tools/ivigenerator/templates_frontend/interface.cpp.tpl
+++ b/src/tools/ivigenerator/templates_frontend/interface.cpp.tpl
@@ -324,6 +324,11 @@ void {{class}}::registerQmlTypes(const QString& uri, int majorVersion, int minor
 /*!
     \qmlproperty {{property|return_type}} {{interface|qml_type}}::{{property}}
 {{ ivi.format_comments(property.comment) }}
+
+{% if property.type.is_enum or property.type.is_flag %}
+    Available values are:
+    \include {{interface.module|lower}}module_enum.qdocinc {{property.type}}
+{% endif %}
 {% if property.const %}
     \note This property is constant and the value will not change once the plugin is initialized.
 {% endif %}
@@ -372,6 +377,18 @@ void {{class}}::registerQmlTypes(const QString& uri, int majorVersion, int minor
 /*!
     \qmlmethod {{interface|qml_type}}::{{operation}}({{ivi.join_params(operation)}})
 {{ ivi.format_comments(operation.comment) }}
+
+{% for param in operation.parameters %}
+{%   if param.type.is_enum or param.type.is_flag %}
+    Available values for {{param}} are:
+    \include {{interface.module|lower}}module_enum.qdocinc {{param.type}}
+{%   endif %}
+
+{% endfor %}
+{%   if operation.type.is_enum or operation.type.is_flag%}
+    Returns the following values:
+    \include {{interface.module|lower}}module_enum.qdocinc {{param.type}}
+{%   endif %}
 */
 /*!
 {{ ivi.format_comments(operation.comment) }}
@@ -456,6 +473,24 @@ void {{class}}::clearServiceObject()
 }
 {% endif %}
 
+{% for signal in interface.signals %}
+/*!
+    \qmlsignal {{interface|qml_type}}::{{signal}}({{ivi.join_params(signal)}})
+{{ ivi.format_comments(signal.comment) }}
+
+{% for param in signal.parameters %}
+{%   if param.type.is_enum or param.type.is_flag %}
+
+    Available values for {{param}} are:
+    \include {{interface.module|lower}}module_enum.qdocinc {{param.type}}
+{%   endif %}
+{% endfor %}
+*/
+/*!
+    \fn {{ivi.signal(signal, class)}}
+{{ ivi.format_comments(signal.comment) }}
+*/
+{% endfor %}
 QT_END_NAMESPACE
 
 #include "moc_{{class|lower}}.cpp"
diff --git a/src/tools/ivigenerator/templates_frontend/module.cpp.tpl b/src/tools/ivigenerator/templates_frontend/module.cpp.tpl
index bf7fab5..4688475 100644
--- a/src/tools/ivigenerator/templates_frontend/module.cpp.tpl
+++ b/src/tools/ivigenerator/templates_frontend/module.cpp.tpl
@@ -38,6 +38,7 @@
 # SPDX-License-Identifier: LGPL-3.0
 #}
 {% set class = '{0}Module'.format(module.module_name|upperfirst) %}
+{% set qml_name = (module|qml_type).split('.')[-1]|upperfirst %}
 {% include 'generated_comment.cpp.tpl' %}
 {% import 'qtivi_macros.j2' as ivi %}
 
@@ -65,7 +66,6 @@ QObject* {{class|lower}}_singletontype_provider(QQmlEngine*, QJSEngine*)
 
     \brief The {{class}} class holds all the enums defined in the {{module}} module.
 */
-
 {% for enum in module.enums %}
 /*!
     \enum {{class}}::{{enum}}
@@ -118,9 +118,8 @@ void {{class}}::registerTypes()
 /*! \internal */
 void {{class}}::registerQmlTypes(const QString& uri, int majorVersion, int minorVersion)
 {
-{% set qml_name = (module|qml_type).split('.')[-1] %}
     qmlRegisterSingletonType<{{class}}>(uri.toLatin1(), majorVersion, minorVersion,
-                                        "{{qml_name|upperfirst}}",
+                                        "{{qml_name}}",
                                         {{class|lower}}_singletontype_provider);
 {% for interface in module.interfaces %}
     {{interface}}::registerQmlTypes(uri, majorVersion, minorVersion);
diff --git a/src/tools/ivigenerator/templates_frontend/module.h.tpl b/src/tools/ivigenerator/templates_frontend/module.h.tpl
index dd81b45..3c1393c 100644
--- a/src/tools/ivigenerator/templates_frontend/module.h.tpl
+++ b/src/tools/ivigenerator/templates_frontend/module.h.tpl
@@ -64,7 +64,7 @@ public:
 {% for enum in module.enums %}
     enum {{enum}} {
         {% for member in enum.members %}
-        {{member.name}} = {{member.value}}, {{member.comment}}
+        {{member.name}} = {{member.value}},
         {% endfor %}
     };
 {% if enum.is_flag %}
diff --git a/src/tools/ivigenerator/templates_frontend/module_qml_enum.qdocinc.tpl b/src/tools/ivigenerator/templates_frontend/module_qml_enum.qdocinc.tpl
new file mode 100644
index 0000000..65e4f88
--- /dev/null
+++ b/src/tools/ivigenerator/templates_frontend/module_qml_enum.qdocinc.tpl
@@ -0,0 +1,51 @@
+{#
+# Copyright (C) 2019 Luxoft Sweden AB
+# Contact: https://www.qt.io/licensing/
+#
+# This file is part of the QtIvi module of the Qt Toolkit.
+#
+# $QT_BEGIN_LICENSE:LGPL-QTAS$
+# Commercial License Usage
+# Licensees holding valid commercial Qt Automotive Suite 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 Lesser General Public License Usage
+# Alternatively, this file may be used under the terms of the GNU Lesser
+# General Public License version 3 as published by the Free Software
+# Foundation and appearing in the file LICENSE.LGPL3 included in the
+# packaging of this file. Please review the following information to
+# ensure the GNU Lesser General Public License version 3 requirements
+# will be met: https://www.gnu.org/licenses/lgpl-3.0.html.
+#
+# GNU General Public License Usage
+# Alternatively, this file may be used under the terms of the GNU
+# General Public License version 2.0 or (at your option) the GNU General
+# Public license version 3 or 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.GPL2 and 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-2.0.html and
+# https://www.gnu.org/licenses/gpl-3.0.html.
+#
+# $QT_END_LICENSE$
+#
+# SPDX-License-Identifier: LGPL-3.0
+#}
+
+{% for enum in module.enums %}
+//! [{{enum}}]
+{%   for member in enum.members %}
+{%     with doc = member.comment|parse_doc %}
+\value {{member.name}}
+{%       if doc.description %}
+       {{doc.description|join(' ')| wordwrap(width=100, wrapstring='\n       ')}}
+{%       endif %}
+{%     endwith %}
+{%   endfor %}
+//! [{{enum}}]
+{% endfor %}
diff --git a/src/tools/ivigenerator/templates_frontend/modulefactory.cpp.tpl b/src/tools/ivigenerator/templates_frontend/modulefactory.cpp.tpl
index f202ecb..b032851 100644
--- a/src/tools/ivigenerator/templates_frontend/modulefactory.cpp.tpl
+++ b/src/tools/ivigenerator/templates_frontend/modulefactory.cpp.tpl
@@ -38,6 +38,7 @@
 # SPDX-License-Identifier: LGPL-3.0
 #}
 {% set class = '{0}ModuleFactory'.format(module.module_name|upperfirst) %}
+{% set qml_name = (module|qml_type).split('.')[-1]|upperfirst %}
 {% include 'generated_comment.cpp.tpl' %}
 
 #include "{{class|lower}}.h"
@@ -50,6 +51,21 @@ QT_BEGIN_NAMESPACE
 
     \brief The {{class}} class provides factory methods for all structs defined in the {{module}} module.
 */
+/*!
+    \qmltype {{qml_name}}
+    \instantiates {{class}}
+    \inqmlmodule {{module|qml_type}}
+
+    \brief The {{qml_name}} singleton holds all the enums defined in the {{module}} module and
+    provides factory methods for all structs.
+
+    The following enums are exported from this object:
+
+{% for enum in module.enums %}
+    \section3 {{enum}}
+    \include {{module|lower}}module_enum.qdocinc {{enum}}
+{% endfor %}
+*/
 {{class}}::{{class}}(QObject *parent)
     : {{module.module_name|upperfirst}}Module(parent)
 {
@@ -57,7 +73,14 @@ QT_BEGIN_NAMESPACE
 
 {% for struct in module.structs %}
 /*!
-    \brief Generate default instance of {{struct}}.
+    \qmlmethod {{struct}} {{module|qml_type}}::{{qml_name}}()
+
+    Returns a default instance of {{struct}}
+
+    \sa {{struct}}
+*/
+/*!
+    Returns a default instance of {{struct}}.
 
     \sa {{struct}}
 */
@@ -67,7 +90,22 @@ QT_BEGIN_NAMESPACE
 }
 
 /*!
-    \brief Generate instance of {{struct}} using attributes.
+    \qmlmethod {{struct}} {{module|qml_type}}::{{qml_name}}({{struct.fields|map('parameter_type')|join(', ')}})
+
+    Returns a default instance of {{struct}}
+
+    \sa {{struct}}
+*/
+/*!
+    Returns a instance of {{struct}} using the passed arguments.
+
+{% for field in struct.fields %}
+{%   if field.type.is_enum or field.type.is_flag %}
+    Available values for {{field}} are:
+    \include {{module|lower}}module_enum.qdocinc {{field.type}}
+{%   endif %}
+
+{% endfor %}
 
     \sa {{struct}}
 */