diff options
author | Dominik Holland <dominik.holland@pelagicore.com> | 2019-01-22 16:01:19 +0100 |
---|---|---|
committer | Dominik Holland <dominik.holland@pelagicore.com> | 2019-02-11 13:42:26 +0000 |
commit | 958e60a4d4b76abd8bf05db0d573daadce0da5e0 (patch) | |
tree | 587b149b306e9c11a575e61fa726a5bde6aaa9f4 | |
parent | a9f486c8836f545f04db8d2bbf83b1b2ee484678 (diff) | |
download | qtivi-958e60a4d4b76abd8bf05db0d573daadce0da5e0.tar.gz |
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>
8 files changed, 135 insertions, 6 deletions
diff --git a/src/ivicore/doc/src/ivigenerator/generator-usage.qdoc b/src/ivicore/doc/src/ivigenerator/generator-usage.qdoc index 3ddefd5..33090d8 100644 --- a/src/ivicore/doc/src/ivigenerator/generator-usage.qdoc +++ b/src/ivicore/doc/src/ivigenerator/generator-usage.qdoc @@ -317,6 +317,9 @@ created. All the generated files will be put in this folder. The following files \li "{{module.module_name|lower}}module.h/cpp" \li Files defining a module class used for module global variables and types. \row + \li "{{module.module_name|lower}}module_enum.qdocinc" + \li Documentation for all values of all enums which can be included by qdoc. + \row \li "{{module|lower|replace('.', '-')}}.pri" \li Standard Qt .pri file, containing all the generated files that can be used for including the autogenerated files into a qmake project. diff --git a/src/tools/ivigenerator/ivigenerator.pro b/src/tools/ivigenerator/ivigenerator.pro index 16af6dd..48771c9 100644 --- a/src/tools/ivigenerator/ivigenerator.pro +++ b/src/tools/ivigenerator/ivigenerator.pro @@ -25,6 +25,7 @@ templates_frontend.files += \ templates_frontend/interface_p.h.tpl \ templates_frontend/module.cpp.tpl \ templates_frontend/module.h.tpl \ + templates_frontend/module_qml_enum.qdocinc.tpl \ templates_frontend/module.pri.tpl \ templates_frontend/modulefactory.cpp.tpl \ templates_frontend/modulefactory.h.tpl \ diff --git a/src/tools/ivigenerator/templates_frontend.yaml b/src/tools/ivigenerator/templates_frontend.yaml index aca230e..654e49a 100644 --- a/src/tools/ivigenerator/templates_frontend.yaml +++ b/src/tools/ivigenerator/templates_frontend.yaml @@ -6,6 +6,8 @@ generate_rules: template_file: "module.h.tpl" - dest_file: "{{module.module_name|lower}}module.cpp" template_file: "module.cpp.tpl" + - dest_file: "{{module.module_name|lower}}module_enum.qdocinc" + template_file: "module_qml_enum.qdocinc.tpl" - dest_file: "{{module.module_name|lower}}modulefactory.h" template_file: "modulefactory.h.tpl" - dest_file: "{{module.module_name|lower}}modulefactory.cpp" 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}} */ |