From 3e9a9e869e47ab4618c13f6374c94d37aacfd608 Mon Sep 17 00:00:00 2001 From: Dominik Holland Date: Wed, 23 Jan 2019 15:46:49 +0100 Subject: ivigenerator: Don't use the javadoc syntax in our qface files In theory the documentation inside the qface files could be transformed using the javadoc syntax and the parse_doc filter function, but so far we only supported the brief tag and already used qdoc commands in the function directly. As the tag functionality of parse_doc is nothing we can really use, better use qdoc commands in the qface documentation right away. Change-Id: I9b23fe84acc6cd942e6fa7ec5933911b84ce22ec Reviewed-by: Robert Griebl --- .../qface-ivi-climate/example-ivi-climate.qface | 42 +++++++++++----------- .../doc/src/ivigenerator/filter-reference.qdoc | 5 +++ src/ivivehiclefunctions/ivivehiclefunctions.qface | 4 +-- src/tools/ivigenerator/common/qtivi_macros.j2 | 8 +---- src/tools/ivigenerator/generate.py | 26 ++++++++++++++ .../auto/core/ivigenerator/org.example.echo.qface | 32 +++++++---------- .../core/ivigenerator/org.example.echo.qtro.qface | 17 +++------ .../ivigenerator/org.example.echo.simulator.qface | 23 ++++-------- 8 files changed, 79 insertions(+), 78 deletions(-) diff --git a/examples/ivicore/qface-ivi-climate/example-ivi-climate.qface b/examples/ivicore/qface-ivi-climate/example-ivi-climate.qface index ec99060..07b5be7 100644 --- a/examples/ivicore/qface-ivi-climate/example-ivi-climate.qface +++ b/examples/ivicore/qface-ivi-climate/example-ivi-climate.qface @@ -10,111 +10,111 @@ module Example.IVI.Climate 1.0; @config: { zoned: true, id: "example.qtivi.ClimateControl/1.0", qml_type: "UiClimateControl" } interface ClimateControl { /** - * @brief Value is true if the air conditioning is enabled. + * \brief Value is true if the air conditioning is enabled. */ bool airConditioning; /** - * @brief value is true if the heater is enabled. + * \brief value is true if the heater is enabled. */ bool heater; /** - * @brief value holds the fan speed level, where the level can be between + * \brief value holds the fan speed level, where the level can be between * minimumValue(off) to maximumValue (strongest). */ @config_simulator: { range: [0, 50] } int fanSpeedLevel; /** - * @brief value holds the steering wheel heater level, where the level can + * \brief value holds the steering wheel heater level, where the level can * be between minimumValue(off) to maximumValue (warmest). */ @config_simulator: { minimum: 0 } int steeringWheelHeater; /** - * @brief value holds the target temperature of the zone expressed + * \brief value holds the target temperature of the zone expressed * in centigrades, where the temperature can be between * minimumValue(coolest) to maximumValue (warmest). */ @config_simulator: { maximum: 30.0 } real targetTemperature; /** - * @brief value holds the seat cooler level, where the level can be + * \brief value holds the seat cooler level, where the level can be * between minimumValue(off) to maximumValue (coolest). */ int seatCooler; /** - * @brief value holds the seat heater level, where the level can be between + * \brief value holds the seat heater level, where the level can be between * minimumValue(off) to maximumValue (warmest). */ int seatHeater; /** - * @brief value holds the outside temperature of the zone expressed in + * \brief value holds the outside temperature of the zone expressed in * centigrades, where the temperature can be between * minimumValue(coolest) to maximumValue (warmest). */ int outsideTemperature; /** - * @brief outside temp lable + * \brief outside temp lable */ @config_simulator: { domain: ["cold", "mild", "warm" ] } string outsideTemperatureLabel; /** - * @brief value is true if the zone synchronization is enabled. + * \brief value is true if the zone synchronization is enabled. * * Which zones and properties are synchronized is controlled * by the backend implementing it. */ bool zoneSynchronization; /** - * @brief value is true if defrost is enabled. Usually that means that the fans + * \brief value is true if defrost is enabled. Usually that means that the fans * are on the highest level to remove ice from the windshield. */ bool defrost; /** - * @brief value holds the recirculation mode + * \brief value holds the recirculation mode */ RecirculationMode recirculationMode; /** - * @brief value is true if the recirculation is currently running. + * \brief value is true if the recirculation is currently running. */ bool recirculation; /** - * @brief value holds the sensitivity level of the recirculation + * \brief value holds the sensitivity level of the recirculation * system when the recirculationMode is set to AutoRecirculation, * where the level can be between minimumValue(least sensitive) * to maximumValue(most sensitive). */ int recirculationSensitivityLevel; /** - * @brief value holds the climate mode + * \brief value holds the climate mode */ ClimateMode climateMode; /** - * @brief value holds the intensity level of the fan when the climateMode + * \brief value holds the intensity level of the fan when the climateMode * is set to AutoClimate, where the level can be between * minimumValue(least intensity) to maximumValue(most intensity). */ int automaticClimateFanIntensityLevel; /** - * @brief value holds the combination of flags indicating the areas + * \brief value holds the combination of flags indicating the areas * where airflow is on. */ AirflowDirection airflowDirections; } /** - * @brief Control where the airflow goes + * \brief Control where the airflow goes */ flag AirflowDirection { /** - * @brief Airflow to the windshield + * \brief Airflow to the windshield */ Windshield = 1, /** - * @brief Airflow to the dashboard + * \brief Airflow to the dashboard */ Dashboard = 2, /** - * @brief Airflow to the floor + * \brief Airflow to the floor */ Floor = 4 } diff --git a/src/ivicore/doc/src/ivigenerator/filter-reference.qdoc b/src/ivicore/doc/src/ivigenerator/filter-reference.qdoc index c0e8d1b..6d06099 100644 --- a/src/ivicore/doc/src/ivigenerator/filter-reference.qdoc +++ b/src/ivicore/doc/src/ivigenerator/filter-reference.qdoc @@ -194,5 +194,10 @@ Returns the parameters for calling the signal using the values from the UI contr Returns the includes for the structs that the interface or a struct depends on. The returned strings are complete and in format #include "struct.h". + +\target comment_text(comment) +\section1 comment_text(comment) + +Returns the text of the passed comment without the leading/trailing comment tokens ('/**', '*'). */ diff --git a/src/ivivehiclefunctions/ivivehiclefunctions.qface b/src/ivivehiclefunctions/ivivehiclefunctions.qface index 030c052..8219ddf 100644 --- a/src/ivivehiclefunctions/ivivehiclefunctions.qface +++ b/src/ivivehiclefunctions/ivivehiclefunctions.qface @@ -3,7 +3,7 @@ module QtIviVehicleFunctions 1.0; /** - * @brief Provides an interface to the climate control. + * \brief Provides an interface to the climate control. * * The QIviClimateControl provides an interface to the climate control of the vehicle. * @@ -168,7 +168,7 @@ enum ClimateMode { } /** - * @brief Provides an interface to the window control. + * \brief Provides an interface to the window control. * * The QIviWindowControl provides an interface to control the physical windows of the vehicle. * diff --git a/src/tools/ivigenerator/common/qtivi_macros.j2 b/src/tools/ivigenerator/common/qtivi_macros.j2 index d35a405..de8cf03 100644 --- a/src/tools/ivigenerator/common/qtivi_macros.j2 +++ b/src/tools/ivigenerator/common/qtivi_macros.j2 @@ -229,11 +229,5 @@ void {{scope}}{{sig}}({{join_params(signal, zoned, default_values)}}) {% macro format_comments(comments) -%} -{% with doc = comments|parse_doc -%} -{% if doc.brief %} \brief {{doc.brief|join(' ')| wordwrap(width=100, wrapstring='\n ')}} -{% endif %} - -{% if doc.description %} - {{doc.description|join(' ')| wordwrap(width=100, wrapstring='\n ')}}{% endif %} -{% endwith -%} +{{comments|comment_text|join('\n ')}} {% endmacro -%} diff --git a/src/tools/ivigenerator/generate.py b/src/tools/ivigenerator/generate.py index c038b42..0517213 100755 --- a/src/tools/ivigenerator/generate.py +++ b/src/tools/ivigenerator/generate.py @@ -652,6 +652,31 @@ def struct_includes(symbol): return includesSet +def comment_text(comment): + """ + Returns the text of the passed comment without the leading/trailing comment tokens e.g. /**, * + """ + comment_start = [ '/**', '/*!', '/*'] + processed = [] + isComment = False + + # No comment is NOT a error + if len(comment) == 0: + return processed + + for token in comment_start: + if (comment.startswith(token)): + isComment = True + break; + if isComment: + comment = comment[3:-2] + else: + return "The provided comment needs to be start with one of these strings: {}".format(comment_start) + + for line in comment.splitlines(): + line = line.lstrip(" *") + processed.append(line) + return processed def generate(tplconfig, moduleConfig, annotations, src, dst): log.debug('run {0} {1}'.format(src, dst)) @@ -695,6 +720,7 @@ def generate(tplconfig, moduleConfig, annotations, src, dst): generator.register_filter('qml_binding_property', qml_binding_property) generator.register_filter('qml_control_signal_parameters', qml_control_signal_parameters) generator.register_filter('struct_includes', struct_includes) + generator.register_filter('comment_text', comment_text) generator.register_filter('hash', qface.filters.hash) diff --git a/tests/auto/core/ivigenerator/org.example.echo.qface b/tests/auto/core/ivigenerator/org.example.echo.qface index 118cf63..ae6249c 100644 --- a/tests/auto/core/ivigenerator/org.example.echo.qface +++ b/tests/auto/core/ivigenerator/org.example.echo.qface @@ -5,23 +5,16 @@ module org.example.echo 1.0 /** - * @brief the brief - * @description the description - * continues {@link http://qt.io} - * @deprecated - * @see org.example.echo.Echo - * @see org.example - * @see http://qt.io - * @anything hello + * \brief the brief + * the description + * continues \l http://qt.io */ @config: {id: "org.foo.id.1.0", qml_class_name: "UiEcho"} interface Echo { /** - * @brief brief message - * @details long message + * \brief brief message * - * @param msg the message - * @return the echo + * Some more documentation */ readonly string lastMessage; int intValue; @@ -50,12 +43,11 @@ interface Echo { @config: {id: "org.foo.idz.1.0", zoned: true} interface EchoZoned { + /** - * @brief brief message - * @details long message + * \brief brief message * - * @param msg the message - * @return the echo + * Some more documentation */ readonly string lastMessage; int intValue; @@ -86,19 +78,19 @@ interface EchoZoned { } /** - * @brief Control where the airflow goes + * \brief Control where the airflow goes */ flag AirflowDirection { /** - * @brief Airflow to the windshield + * \brief Airflow to the windshield */ Windshield = 1, /** - * @brief Airflow to the dashboard + * \brief Airflow to the dashboard */ Dashboard = 2, /** - * @brief Airflow to the floor + * \brief Airflow to the floor */ Floor = 4 } diff --git a/tests/auto/core/ivigenerator/org.example.echo.qtro.qface b/tests/auto/core/ivigenerator/org.example.echo.qtro.qface index 9d4b93b..79d691b 100644 --- a/tests/auto/core/ivigenerator/org.example.echo.qtro.qface +++ b/tests/auto/core/ivigenerator/org.example.echo.qtro.qface @@ -5,23 +5,16 @@ module org.example.echo 1.0 /** - * @brief the brief - * @description the description - * continues {@link http://qt.io} - * @deprecated - * @see org.example.echo.Echo - * @see org.example - * @see http://qt.io - * @anything hello + * \brief the brief + * the description + * continues \l http://qt.io */ @config: {id: "org.foo.id.1.0", qml_class_name: "UiEcho"} interface Echo { /** - * @brief brief message - * @details long message + * \brief brief message * - * @param msg the message - * @return the echo + * Some more documentation */ readonly string lastMessage; int intValue; diff --git a/tests/auto/core/ivigenerator/org.example.echo.simulator.qface b/tests/auto/core/ivigenerator/org.example.echo.simulator.qface index 3d77205..6b39cd2 100644 --- a/tests/auto/core/ivigenerator/org.example.echo.simulator.qface +++ b/tests/auto/core/ivigenerator/org.example.echo.simulator.qface @@ -4,23 +4,16 @@ module org.example.simulator.echo 1.0 /** - * @brief the brief - * @description the description - * continues {@link http://qt.io} - * @deprecated - * @see org.example.echo.Echo - * @see org.example - * @see http://qt.io - * @anything hello + * \brief the brief + * the description + * continues \l http://qt.io */ @config: {"id": "org.foo.id.1.0"} interface Echo { /** - * @brief brief message - * @details long message + * \brief brief message * - * @param msg the message - * @return the echo + * Some more documentation */ readonly string lastMessage; int intValue; @@ -35,11 +28,9 @@ interface Echo { @config: {"id": "org.foo.idz.1.0", "zoned": true} interface EchoZoned { /** - * @brief brief message - * @details long message + * \brief brief message * - * @param msg the message - * @return the echo + * Some more documentation */ readonly string lastMessage; int intValue; -- cgit v1.2.1