From 76cc799cd2d7305afc8375a2bddbcff0ef4e18c2 Mon Sep 17 00:00:00 2001 From: Topi Reinio Date: Tue, 10 Mar 2020 23:53:29 +0100 Subject: Enforce zero warnings for QDoc's generatedoutput autotest Fix all QDoc warnings for the tests and set the warning limit to zero. If any warnings are introduced, QDoc will exit with non-zero value and the test will fail. The exceptions are the tests specific to the DocBook generator, where we expect to see two warnings related to shared comment nodes. The generator currently has trouble handling these. Fixes: QTBUG-82808 Change-Id: I0482516e1e34b92592d921a4a0ffb41e4b2b4770 Reviewed-by: Paul Wicking --- .../docbook/test-componentset-example.xml | 14 +++++++------- .../expected_output/docbook/uicomponents-qmlmodule.xml | 2 +- .../expected_output/includefromexampledirs/index.html | 2 ++ .../qml-qdoc-test-abstractparent-members.html | 3 +-- .../qml-qdoc-test-abstractparent.html | 14 ++------------ .../generatedoutput/testdata/configs/docbook.qdocconf | 4 ++++ .../generatedoutput/testdata/configs/test.qdocconf | 4 ++++ .../generatedoutput/testdata/configs/testcpp.qdocconf | 5 +++++ .../includefromexampledirs/excludes/parentinclude.qdoc | 14 +------------- .../includefromexampledirs.qdocconf | 2 ++ .../includefromexampledirs/src/includefromparent.qdoc | 15 +++++++++++++++ .../testdata/qml/componentset/examples.qdoc | 18 +++++++++--------- .../qdoc/generatedoutput/testdata/testcpp/testcpp.cpp | 2 +- 13 files changed, 54 insertions(+), 45 deletions(-) diff --git a/tests/auto/qdoc/generatedoutput/expected_output/docbook/test-componentset-example.xml b/tests/auto/qdoc/generatedoutput/expected_output/docbook/test-componentset-example.xml index 2b442d1dd..48496733b 100644 --- a/tests/auto/qdoc/generatedoutput/expected_output/docbook/test-componentset-example.xml +++ b/tests/auto/qdoc/generatedoutput/expected_output/docbook/test-componentset-example.xml @@ -10,29 +10,29 @@ This example demonstrates one of the ways to document QML types. In particular, there are sample types that are documented with QDoc commands comments. There are documentation comments for the QML types and their public interfaces. The types are grouped into a module, the UI Components module. -The uicomponents.qdoc file generates the overview page for the UI Components module page. +The uicomponents.qdoc file generates the overview page for the UI Components module page. The generated documentation is available in the UI Components module. QML Class -The QML types use the \qmltype to document the type. In addition, they have the \inmodule command in order for QDoc to associate them to the UIComponents module. -QDoc uses the \brief command to place a basic description when listing the types. +The QML types use the \qmltype to document the type. In addition, they have the \inmodule command in order for QDoc to associate them to the UIComponents module. +QDoc uses the \brief command to place a basic description when listing the types. Properties, Signals, Handlers, and Methods The types have their properties, signals, handlers, and methods defined in their respective QML files. QDoc associates the properties and methods to the types, therefore, you only need to place the documentation above the property, method, or signal. -To document the type of a property alias, you must use the \qmlproperty command to specify the data type. +To document the type of a property alias, you must use the \qmlproperty command to specify the data type. \qmlproperty <@type>int</@type> anAliasedProperty An aliased property of type <@type>int</@type><@op>.</@op> Internal Documentation -You may declare that a documentation is for internal use by placing the \internal command after the beginning QDoc comment /*. QDoc will prevent the internal documentation from appearing in the public API. -If you wish to omit certain parts of the documentation, you may use the \omit and \endomit command. +You may declare that a documentation is for internal use by placing the \internal command after the beginning QDoc comment /*. QDoc will prevent the internal documentation from appearing in the public API. +If you wish to omit certain parts of the documentation, you may use the \omit and \endomit command. QML Types with C++ Implementation -This example only demonstrates the documentation for types in QML files, but the regular QML commands may be placed inside C++ classes to define the public API of the QML type. +This example only demonstrates the documentation for types in QML files, but the regular QML commands may be placed inside C++ classes to define the public API of the QML type. Files: diff --git a/tests/auto/qdoc/generatedoutput/expected_output/docbook/uicomponents-qmlmodule.xml b/tests/auto/qdoc/generatedoutput/expected_output/docbook/uicomponents-qmlmodule.xml index f43890289..f00b3d3f7 100644 --- a/tests/auto/qdoc/generatedoutput/expected_output/docbook/uicomponents-qmlmodule.xml +++ b/tests/auto/qdoc/generatedoutput/expected_output/docbook/uicomponents-qmlmodule.xml @@ -9,7 +9,7 @@ -This is a listing of a list of UI components implemented by QML types. These files are available for general import and they are based on the Qt Quick Code Samples. +This is a listing of a list of UI components implemented by QML types. These files are available for general import and they are based on the Qt Quick Code Samples. This module is part of the UIComponents example. diff --git a/tests/auto/qdoc/generatedoutput/expected_output/includefromexampledirs/index.html b/tests/auto/qdoc/generatedoutput/expected_output/includefromexampledirs/index.html index d1fb02484..fd9fdd50a 100644 --- a/tests/auto/qdoc/generatedoutput/expected_output/includefromexampledirs/index.html +++ b/tests/auto/qdoc/generatedoutput/expected_output/includefromexampledirs/index.html @@ -20,6 +20,8 @@

QML Types

+ +

AbstractParent

Abstract base QML type

Child

A Child inheriting its parent

int

An integer basic type

Test include file that is part of the sourcedirs.

diff --git a/tests/auto/qdoc/generatedoutput/expected_output/includefromexampledirs/qml-qdoc-test-abstractparent-members.html b/tests/auto/qdoc/generatedoutput/expected_output/includefromexampledirs/qml-qdoc-test-abstractparent-members.html index 48c8fa485..f9d64de75 100644 --- a/tests/auto/qdoc/generatedoutput/expected_output/includefromexampledirs/qml-qdoc-test-abstractparent-members.html +++ b/tests/auto/qdoc/generatedoutput/expected_output/includefromexampledirs/qml-qdoc-test-abstractparent-members.html @@ -2,7 +2,7 @@ - + List of All Members for AbstractParent | Test @@ -11,7 +11,6 @@

This is the complete list of members for AbstractParent, including inherited members.

diff --git a/tests/auto/qdoc/generatedoutput/expected_output/includefromexampledirs/qml-qdoc-test-abstractparent.html b/tests/auto/qdoc/generatedoutput/expected_output/includefromexampledirs/qml-qdoc-test-abstractparent.html index cbb0f36aa..f7c294ae0 100644 --- a/tests/auto/qdoc/generatedoutput/expected_output/includefromexampledirs/qml-qdoc-test-abstractparent.html +++ b/tests/auto/qdoc/generatedoutput/expected_output/includefromexampledirs/qml-qdoc-test-abstractparent.html @@ -2,7 +2,7 @@ - + AbstractParent QML Type | Test @@ -34,12 +34,12 @@

Methods

Detailed Description

+

Test include file that is part of the sourcedirs.

Property Documentation

@@ -54,16 +54,6 @@

Method Documentation

- -
-
- - -

-void rear(child)

-

Do some abstract parenting on child.

-
-
diff --git a/tests/auto/qdoc/generatedoutput/testdata/configs/docbook.qdocconf b/tests/auto/qdoc/generatedoutput/testdata/configs/docbook.qdocconf index 6fe708176..68afd29e8 100644 --- a/tests/auto/qdoc/generatedoutput/testdata/configs/docbook.qdocconf +++ b/tests/auto/qdoc/generatedoutput/testdata/configs/docbook.qdocconf @@ -1,3 +1,7 @@ outputformats = DocBook DocBook.nosubdirs = true DocBook.outputsubdir = docbook + +# TODO: DocBook generator has trouble handling shared comment nodes +# allow two warnings related to these +warninglimit = 2 diff --git a/tests/auto/qdoc/generatedoutput/testdata/configs/test.qdocconf b/tests/auto/qdoc/generatedoutput/testdata/configs/test.qdocconf index f6473ccf7..e4cef822e 100644 --- a/tests/auto/qdoc/generatedoutput/testdata/configs/test.qdocconf +++ b/tests/auto/qdoc/generatedoutput/testdata/configs/test.qdocconf @@ -6,3 +6,7 @@ sources = ../outputfromqdocfiles/qdoctests-outputfromqdocfiles.qdoc macro.beginqdoc = "\\c {/*!}" macro.endqdoc = "\\c */" + +# zero warning tolerance +warninglimit = 0 +warninglimit.enabled = true diff --git a/tests/auto/qdoc/generatedoutput/testdata/configs/testcpp.qdocconf b/tests/auto/qdoc/generatedoutput/testdata/configs/testcpp.qdocconf index ff10ae4be..b07aa71c0 100644 --- a/tests/auto/qdoc/generatedoutput/testdata/configs/testcpp.qdocconf +++ b/tests/auto/qdoc/generatedoutput/testdata/configs/testcpp.qdocconf @@ -5,4 +5,9 @@ headers = ../testcpp/testcpp.h sources = ../testcpp/testcpp.cpp macro.CMDFN = \\\\fn +macro.nothing = \\dontdocument () locationinfo = false + +# zero warning tolerance +warninglimit = 0 +warninglimit.enabled = true diff --git a/tests/auto/qdoc/generatedoutput/testdata/includefromexampledirs/excludes/parentinclude.qdoc b/tests/auto/qdoc/generatedoutput/testdata/includefromexampledirs/excludes/parentinclude.qdoc index c95e22125..4933bc4bd 100644 --- a/tests/auto/qdoc/generatedoutput/testdata/includefromexampledirs/excludes/parentinclude.qdoc +++ b/tests/auto/qdoc/generatedoutput/testdata/includefromexampledirs/excludes/parentinclude.qdoc @@ -29,6 +29,7 @@ /*! //! abstract-type \qmltype AbstractParent + \inqmlmodule QDoc.Test \ingroup qmltypes \qmlabstract \brief Abstract base QML type. @@ -49,16 +50,3 @@ \brief Do some abstract parenting on \a child. //! rear-qmlmethod */ - -/*! - \qmltype Child - \ingroup qmltypes - \inherits AbstractParent - \brief A Child inheriting its parent. -*/ - -/*! - \qmlbasictype int - \ingroup qmltypes - \brief An integer basic type. -*/ diff --git a/tests/auto/qdoc/generatedoutput/testdata/includefromexampledirs/includefromexampledirs.qdocconf b/tests/auto/qdoc/generatedoutput/testdata/includefromexampledirs/includefromexampledirs.qdocconf index 1d981deb2..d64985942 100644 --- a/tests/auto/qdoc/generatedoutput/testdata/includefromexampledirs/includefromexampledirs.qdocconf +++ b/tests/auto/qdoc/generatedoutput/testdata/includefromexampledirs/includefromexampledirs.qdocconf @@ -5,6 +5,8 @@ sourcedirs += src excludedirs += excludes \ ../qml/componentset +excludefiles += ../qml/parent.qdoc + exampledirs += excludes HTML.nosubdirs = true diff --git a/tests/auto/qdoc/generatedoutput/testdata/includefromexampledirs/src/includefromparent.qdoc b/tests/auto/qdoc/generatedoutput/testdata/includefromexampledirs/src/includefromparent.qdoc index 7b4c00b76..a9a526c64 100644 --- a/tests/auto/qdoc/generatedoutput/testdata/includefromexampledirs/src/includefromparent.qdoc +++ b/tests/auto/qdoc/generatedoutput/testdata/includefromexampledirs/src/includefromparent.qdoc @@ -49,3 +49,18 @@ \include parent.qdocinc */ + +/*! + \qmltype Child + \inqmlmodule QDoc.Test + \ingroup qmltypes + \inherits AbstractParent + \brief A Child inheriting its parent. +*/ + +/*! + \qmlbasictype int + \inqmlmodule QDoc.Test + \ingroup qmltypes + \brief An integer basic type. +*/ diff --git a/tests/auto/qdoc/generatedoutput/testdata/qml/componentset/examples.qdoc b/tests/auto/qdoc/generatedoutput/testdata/qml/componentset/examples.qdoc index 2f56c221c..0816e624c 100644 --- a/tests/auto/qdoc/generatedoutput/testdata/qml/componentset/examples.qdoc +++ b/tests/auto/qdoc/generatedoutput/testdata/qml/componentset/examples.qdoc @@ -40,18 +40,18 @@ and their public interfaces. The types are grouped into a module, the \l{UI Components} module. - The \l{componentset/uicomponents.qdoc.sample}{uicomponents.qdoc} file generates + The uicomponents.qdoc file generates the overview page for the \l{UI Components} module page. The generated documentation is available in the \l{UI Components} module. \section1 QML Class - The QML types use the \l{qmltype-command}{\\qmltype} to document the - type. In addition, they have the \l{inmodule-command}{\\inmodule} + The QML types use the \\qmltype to document the + type. In addition, they have the \\inmodule command in order for QDoc to associate them to the \c UIComponents module. - QDoc uses the \l{brief-command}{\\brief} command to place a basic + QDoc uses the \\brief command to place a basic description when listing the types. \section1 Properties, Signals, Handlers, and Methods @@ -62,7 +62,7 @@ documentation above the property, method, or signal. To document the type of a \e {property alias}, you must use the - \l{qmlproperty-command}{\\qmlproperty} command to specify the data type. + \\qmlproperty command to specify the data type. \code \qmlproperty int anAliasedProperty @@ -72,17 +72,17 @@ \section2 Internal Documentation You may declare that a documentation is for internal use by placing the - \l{internal-command}{\\internal} command after the beginning QDoc comment + \\internal command after the beginning QDoc comment \begincomment. QDoc will prevent the internal documentation from appearing in the public API. If you wish to omit certain parts of the documentation, you may use the - \l{omit-command}{\\omit} and \l{omit-command}{\\endomit} command. + \\omit and \\endomit command. \section1 QML Types with C++ Implementation This example only demonstrates the documentation for types in QML - files, but the regular \l{qml-documentation}{QML commands} may be placed + files, but the regular QML commands may be placed inside C++ classes to define the public API of the QML type. */ @@ -95,7 +95,7 @@ This is a listing of a list of UI components implemented by QML types. These files are available for general import and they are based on the - \l{Qt Quick Examples and Tutorials}{Qt Quick Code Samples}. + Qt Quick Code Samples. This module is part of the \l{componentset}{UIComponents} example. */ diff --git a/tests/auto/qdoc/generatedoutput/testdata/testcpp/testcpp.cpp b/tests/auto/qdoc/generatedoutput/testdata/testcpp/testcpp.cpp index 643a6db6a..b1acdccf0 100644 --- a/tests/auto/qdoc/generatedoutput/testdata/testcpp/testcpp.cpp +++ b/tests/auto/qdoc/generatedoutput/testdata/testcpp/testcpp.cpp @@ -167,7 +167,7 @@ void TestDerived::virtualFun() \fn template void TestQDoc::Test::funcTemplate(T1 a, T2 b) \brief Function template with two parameters, \a a and \a b. \else - //! nothing + \nothing \endif */ -- cgit v1.2.3