From c6665d7ebf68cb3a1ed15527309eb70ffe927536 Mon Sep 17 00:00:00 2001 From: Thibaut Cuvelier Date: Fri, 10 Feb 2023 04:16:34 +0100 Subject: QDoc DocBook: add new test suite for the extension tags MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Explicitly test that the right tags are output when the DocBook 5.2 extensions are enabled. This test suite is made small intentionally, because the extensions do not have an impact on that many pages. Pick-to: 6.5 Change-Id: I6a135ddb20f17034287e0a6d5da4a5b96e064028 Reviewed-by: Topi Reiniö Reviewed-by: Paul Wicking --- .../docbookext/qdoc-test-qmlmodule.xml | 54 ++++ .../qdoctests-qdocfileoutput-exhaustive.xml | 125 +++++++ .../qdoctests-qdocfileoutput-linking.xml | 19 ++ .../docbookext/qdoctests-qdocfileoutput.xml | 80 +++++ .../qdoctests-qdocmanuallikefileoutput.xml | 56 ++++ .../expected_output/docbookext/qml-int.xml | 36 +++ .../docbookext/qml-qdoc-test-abstractparent.xml | 79 +++++ .../docbookext/qml-qdoc-test-child.xml | 79 +++++ .../docbookext/qml-qdoc-test-doctest.xml | 117 +++++++ .../docbookext/qml-qdoc-test-type.xml | 230 +++++++++++++ .../docbookext/qml-qdoc-test-yetanotherchild.xml | 44 +++ .../docbookext/qml-test-nover-typenoversion.xml | 41 +++ .../docbookext/qml-uicomponents-progressbar.xml | 104 ++++++ .../docbookext/qml-uicomponents-switch.xml | 47 +++ .../docbookext/qml-uicomponents-tabwidget.xml | 77 +++++ .../docbookext/test-componentset-example.xml | 55 ++++ .../docbookext/test-nover-qmlmodule.xml | 24 ++ .../expected_output/docbookext/testcpp-module.xml | 83 +++++ .../expected_output/docbookext/testqdoc-test.xml | 358 +++++++++++++++++++++ .../docbookext/testqdoc-testderived.xml | 114 +++++++ .../expected_output/docbookext/testqdoc.xml | 72 +++++ .../docbookext/uicomponents-qmlmodule.xml | 34 ++ .../testdata/configs/docbook.qdocconf | 4 +- .../testdata/configs/docbookext.qdocconf | 8 + .../testdata/configs/docbookext_test.qdocconf | 3 + .../testdata/configs/docbookext_testcpp.qdocconf | 3 + .../testdata/configs/docbookext_testqml.qdocconf | 3 + .../qdoc/generatedoutput/tst_generatedoutput.cpp | 42 ++- 28 files changed, 1988 insertions(+), 3 deletions(-) create mode 100644 tests/auto/qdoc/generatedoutput/expected_output/docbookext/qdoc-test-qmlmodule.xml create mode 100644 tests/auto/qdoc/generatedoutput/expected_output/docbookext/qdoctests-qdocfileoutput-exhaustive.xml create mode 100644 tests/auto/qdoc/generatedoutput/expected_output/docbookext/qdoctests-qdocfileoutput-linking.xml create mode 100644 tests/auto/qdoc/generatedoutput/expected_output/docbookext/qdoctests-qdocfileoutput.xml create mode 100644 tests/auto/qdoc/generatedoutput/expected_output/docbookext/qdoctests-qdocmanuallikefileoutput.xml create mode 100644 tests/auto/qdoc/generatedoutput/expected_output/docbookext/qml-int.xml create mode 100644 tests/auto/qdoc/generatedoutput/expected_output/docbookext/qml-qdoc-test-abstractparent.xml create mode 100644 tests/auto/qdoc/generatedoutput/expected_output/docbookext/qml-qdoc-test-child.xml create mode 100644 tests/auto/qdoc/generatedoutput/expected_output/docbookext/qml-qdoc-test-doctest.xml create mode 100644 tests/auto/qdoc/generatedoutput/expected_output/docbookext/qml-qdoc-test-type.xml create mode 100644 tests/auto/qdoc/generatedoutput/expected_output/docbookext/qml-qdoc-test-yetanotherchild.xml create mode 100644 tests/auto/qdoc/generatedoutput/expected_output/docbookext/qml-test-nover-typenoversion.xml create mode 100644 tests/auto/qdoc/generatedoutput/expected_output/docbookext/qml-uicomponents-progressbar.xml create mode 100644 tests/auto/qdoc/generatedoutput/expected_output/docbookext/qml-uicomponents-switch.xml create mode 100644 tests/auto/qdoc/generatedoutput/expected_output/docbookext/qml-uicomponents-tabwidget.xml create mode 100644 tests/auto/qdoc/generatedoutput/expected_output/docbookext/test-componentset-example.xml create mode 100644 tests/auto/qdoc/generatedoutput/expected_output/docbookext/test-nover-qmlmodule.xml create mode 100644 tests/auto/qdoc/generatedoutput/expected_output/docbookext/testcpp-module.xml create mode 100644 tests/auto/qdoc/generatedoutput/expected_output/docbookext/testqdoc-test.xml create mode 100644 tests/auto/qdoc/generatedoutput/expected_output/docbookext/testqdoc-testderived.xml create mode 100644 tests/auto/qdoc/generatedoutput/expected_output/docbookext/testqdoc.xml create mode 100644 tests/auto/qdoc/generatedoutput/expected_output/docbookext/uicomponents-qmlmodule.xml create mode 100644 tests/auto/qdoc/generatedoutput/testdata/configs/docbookext.qdocconf create mode 100644 tests/auto/qdoc/generatedoutput/testdata/configs/docbookext_test.qdocconf create mode 100644 tests/auto/qdoc/generatedoutput/testdata/configs/docbookext_testcpp.qdocconf create mode 100644 tests/auto/qdoc/generatedoutput/testdata/configs/docbookext_testqml.qdocconf diff --git a/tests/auto/qdoc/generatedoutput/expected_output/docbookext/qdoc-test-qmlmodule.xml b/tests/auto/qdoc/generatedoutput/expected_output/docbookext/qdoc-test-qmlmodule.xml new file mode 100644 index 000000000..cbdeb19b1 --- /dev/null +++ b/tests/auto/qdoc/generatedoutput/expected_output/docbookext/qdoc-test-qmlmodule.xml @@ -0,0 +1,54 @@ + + + +QDoc.Test QML Module +Test +A test project for QDoc build artifacts + +QML Types for the Test module. +This module is under development and is subject to change. +This module was introduced in Qt 1.1. + + +This module is under development and is subject to change. +This module was introduced in Qt 1.1. + + + +DocTest + +Represents a doc test case. + + + +AbstractParent + +Abstract base QML type. + + + +Child + +A Child inheriting its parent. + + + +int + +An integer value type. + + + +YetAnotherChild + +A type inheriting from internal abstract parent. + + + +Type + +A QML type documented in a .cpp file. + + + + diff --git a/tests/auto/qdoc/generatedoutput/expected_output/docbookext/qdoctests-qdocfileoutput-exhaustive.xml b/tests/auto/qdoc/generatedoutput/expected_output/docbookext/qdoctests-qdocfileoutput-exhaustive.xml new file mode 100644 index 000000000..878fb3211 --- /dev/null +++ b/tests/auto/qdoc/generatedoutput/expected_output/docbookext/qdoctests-qdocfileoutput-exhaustive.xml @@ -0,0 +1,125 @@ + + + +Exhaustive testing of QDoc commands +OutputFromQDocFiles +OutputFromQDocFiles - A test project for QDoc build artifacts +A test project for QDoc build artifacts + +This page is a dumping ground for QDoc commands under test. + + + +This is a section1 + +This is a section2 + +This is a section3 + +This is a section4 +This is bad code + +This text should have a line break riiiiight noooow. +All your text belong to bold ...And this is an examble of only bold being, well, bold. + ... + +This a caption +Lorem legal ipsum +This is a quotation. + +This is raw. Like the

Eddie Murphy

movie. Just not as funny.]]> +Look, ma! I made a sidebar! + + + + +Table item in a table row + + + + +Another item in a different row + + + + +This is really important. + + +The code above doesn't compile + + + + + + +Images +An image without any text: + + + + + +An image with just an alternative text: + +Image alt + + + + +An image with alternative text and 1-atom caption: + +Image caption + +Image alt + + + + + +An image with alternative text and 2-atom caption: + +Image caption with bold text + +Image alt + + + + + +A bordered image: + + + + + +A bordered image with a caption: + +Screenshot of the System Tray Icon + + + + + + +An inline image: +The is a paragraph containing an + + + + inline image to test if qdoc handles them properly, without considering rest of the line as alt text for the image. +An inline image with alt text: +Here is another example of +No. 1 + + + + inline image with alternative text, which should be added as an attribute to the inline image. + + +Commands not yet tested + +The following commands have yet to be tested: footnote link sincelist header index topicref // or just don’t care, remove it inlineimage printline printto printuntil // what’s the difference between printto and printuntil??? quotefile quotefromfile skipline skipto skipuntil span snippet codeline overload sub sup tableofcontents tt uicontrol endmapref endomit underline unicode + + + diff --git a/tests/auto/qdoc/generatedoutput/expected_output/docbookext/qdoctests-qdocfileoutput-linking.xml b/tests/auto/qdoc/generatedoutput/expected_output/docbookext/qdoctests-qdocfileoutput-linking.xml new file mode 100644 index 000000000..51b7e62b3 --- /dev/null +++ b/tests/auto/qdoc/generatedoutput/expected_output/docbookext/qdoctests-qdocfileoutput-linking.xml @@ -0,0 +1,19 @@ + + + +Testing QDoc's link command +OutputFromQDocFiles +OutputFromQDocFiles - A test project for QDoc build artifacts +A test project for QDoc build artifacts + + + +This is a page for testing QDoc's link command. + + + + +Link targets +Valid parameters for the link command (\l) are page and section titles, targets defined with \target or \keyword commands, and API reference keywords (types, methods, namespaces, and so on). + + diff --git a/tests/auto/qdoc/generatedoutput/expected_output/docbookext/qdoctests-qdocfileoutput.xml b/tests/auto/qdoc/generatedoutput/expected_output/docbookext/qdoctests-qdocfileoutput.xml new file mode 100644 index 000000000..72905681d --- /dev/null +++ b/tests/auto/qdoc/generatedoutput/expected_output/docbookext/qdoctests-qdocfileoutput.xml @@ -0,0 +1,80 @@ + + + +Testing QDoc output from .qdoc files +OutputFromQDocFiles +OutputFromQDocFiles - A test project for QDoc build artifacts +A test project for QDoc build artifacts + + +This is a simple page for testing purposes only. + + +QDoc generates documentation for software projects. It does this by extracting QDoc comments from project source files. QDoc comments are signified by a C-style-like comment tag followed by an exclamation point, like this: /*! This text is contained within QDoc comment tags. */. + +Supported file types +QDoc parses .cpp and .qdoc files. It does extract comments from header (.h) files. + + +Further information +This test document is written with the purpose of testing the output QDoc generates when parsing .qdoc files. It is fairly simple and makes use of a limited subset of QDoc's command. Those commands are: + + +\page + + +\title + + +\brief + + +\e (for emphasizing "QDoc comments") + + +\c (for multiple monospace-formatted entries) + + +\section1 + + +\list + + +\li + + +\endlist + + + + +Linking +There are multiple ways to create hyperlinks to other topics: + + +Linking to a page title + + +Linking to a section title + + +Linking using a \target string + + +Linking using a \keyword string + + + + +QDoc Linking Test +This section title is overridden by another target which takes precedence. + + +Linking to something in a section title +This is allowed but a questionable practice. + +You're looking at detailed information. + + + diff --git a/tests/auto/qdoc/generatedoutput/expected_output/docbookext/qdoctests-qdocmanuallikefileoutput.xml b/tests/auto/qdoc/generatedoutput/expected_output/docbookext/qdoctests-qdocmanuallikefileoutput.xml new file mode 100644 index 000000000..8372f150c --- /dev/null +++ b/tests/auto/qdoc/generatedoutput/expected_output/docbookext/qdoctests-qdocmanuallikefileoutput.xml @@ -0,0 +1,56 @@ + + + +Document Navigation +OutputFromQDocFiles +OutputFromQDocFiles - A test project for QDoc build artifacts +A test project for QDoc build artifacts + +A test project for QDoc build artifacts. + +The navigation commands... + + + +

+ [Previous: + Basic Qt] + [Contents] + [Next: + Creating Dialogs] +

+ +

Getting Started

+ +

+ This chapter shows how to combine basic C++ with the + functionality provided by Qt to create a few small graphical + interface (GUI) applications. +

+ +

+ [Previous: + Basic Qt] + [Contents] + [Next: + Creating Dialogs] +

+ + + ]]> + +&lt;head&gt; + ... + &lt;link rel=&quot;start&quot; href=&quot;basicqt.html&quot; /&gt; + ... +&lt;/head&gt; + + +Commands + + +\previouspage +The \previouspage command... + + + diff --git a/tests/auto/qdoc/generatedoutput/expected_output/docbookext/qml-int.xml b/tests/auto/qdoc/generatedoutput/expected_output/docbookext/qml-int.xml new file mode 100644 index 000000000..c7ce09e55 --- /dev/null +++ b/tests/auto/qdoc/generatedoutput/expected_output/docbookext/qml-int.xml @@ -0,0 +1,36 @@ + + + +int QML Value Type +Test +A test project for QDoc build artifacts + +An integer value type. +This type was introduced in Qt 1.1. + + + + +Import Statement + +import QDoc.Test 1.1 + + + +Since: + +Qt 1.1 + + + + +Detailed Description + + +Method Documentation + +int abs() +Returns the absolute value of this integer. + + + diff --git a/tests/auto/qdoc/generatedoutput/expected_output/docbookext/qml-qdoc-test-abstractparent.xml b/tests/auto/qdoc/generatedoutput/expected_output/docbookext/qml-qdoc-test-abstractparent.xml new file mode 100644 index 000000000..154b70b0f --- /dev/null +++ b/tests/auto/qdoc/generatedoutput/expected_output/docbookext/qml-qdoc-test-abstractparent.xml @@ -0,0 +1,79 @@ + + + +AbstractParent QML Type +Test +A test project for QDoc build artifacts + +Abstract base QML type. +This type was introduced in Qt 1.1. + + + + +Import Statement + +import QDoc.Test 1.1 + + + +Since: + +Qt 1.1 + + + +Inherited By: + +Child + + + + +Detailed Description + + +Property Documentation + +[default] children : list<Child> + +list<Child> +children +writable +[default] + +public +active +unspecified + +Children of the type. + + +name : string + +string +name +writable +public +active +unspecified + +Name of this parent. + + + +Method Documentation + +void name(Child child, name) +Name a child using name. + + +void name() +Name all children with random names. + + +void rear(Child child, var method = Strict) +Do some abstract parenting on child using a specific method. + + + diff --git a/tests/auto/qdoc/generatedoutput/expected_output/docbookext/qml-qdoc-test-child.xml b/tests/auto/qdoc/generatedoutput/expected_output/docbookext/qml-qdoc-test-child.xml new file mode 100644 index 000000000..76df460b7 --- /dev/null +++ b/tests/auto/qdoc/generatedoutput/expected_output/docbookext/qml-qdoc-test-child.xml @@ -0,0 +1,79 @@ + + + +Child QML Type +Test +A test project for QDoc build artifacts + +A Child inheriting its parent. +This type was introduced in Qt 1.1. + + + + +Import Statement + +import QDoc.Test 1.1 + + + +Since: + +Qt 1.1 + + + +Inherits: + +AbstractParent + + + + +Detailed Description + + +Property Documentation + +[default] children : list<Child> + +list<Child> +children +writable +[default] + +public +active +unspecified + +Children of the type. + + +name : string + +string +name +writable +public +active +unspecified + +Name of this child. + + + +Method Documentation + +void name(Child child, name) +Name a child of this child using name. + + +void name() +Name all children with random names. + + +void rear(Child child, var method = Strict) +Do some abstract parenting on child using a specific method. + + + diff --git a/tests/auto/qdoc/generatedoutput/expected_output/docbookext/qml-qdoc-test-doctest.xml b/tests/auto/qdoc/generatedoutput/expected_output/docbookext/qml-qdoc-test-doctest.xml new file mode 100644 index 000000000..d39a330bb --- /dev/null +++ b/tests/auto/qdoc/generatedoutput/expected_output/docbookext/qml-qdoc-test-doctest.xml @@ -0,0 +1,117 @@ + + + +DocTest QML Type +Test +A test project for QDoc build artifacts + +Represents a doc test case. +This type was introduced in QDoc.Test 0.9. + + + + +Import Statement + +import QDoc.Test 1.1 + + + +Since: + +QDoc.Test 0.9 + + + + +Detailed Description + +Introduction +A documentation test case, itself documented inline in DocTest.qml. + + + +Property Documentation + +[default: true] active : bool + +bool +active +writable +public +active +unspecified + +Whether the test is active. + +See Also +See also + +name + + + + + +[required] name : string + +string +name +writable +required +public +active +unspecified + +Name of the test. +DocTest { + name: &quot;test&quot; + // ... +} + + + + +Signal Documentation + +completed() + +The corresponding handler is onCompleted. + + + +foo(var bar) +Signal with parameter bar. + +The corresponding handler is onFoo. + + + +itsHappening(bool really) +Signals that something is really happening. + +The corresponding handler is onItsHappening. + + + + +Method Documentation + +[since QDoc.Test 1.0] fail(message = "oops") +Fails the current test case, with the optional message. +This method was introduced in QDoc.Test 1.0. + + +fail_hard(msg = "facepalm", option = 123) +Fails the current test case, hard. + + +Prints out msg. + + +Accepts a random option. + + + + + diff --git a/tests/auto/qdoc/generatedoutput/expected_output/docbookext/qml-qdoc-test-type.xml b/tests/auto/qdoc/generatedoutput/expected_output/docbookext/qml-qdoc-test-type.xml new file mode 100644 index 000000000..4422b6962 --- /dev/null +++ b/tests/auto/qdoc/generatedoutput/expected_output/docbookext/qml-qdoc-test-type.xml @@ -0,0 +1,230 @@ + + + +Type QML Type +Test +A test project for QDoc build artifacts + +A QML type documented in a .cpp file. +This type was introduced in Qt 1.1. + + + + +Import Statement + +import QDoc.Test 1.1 + + + +Since: + +Qt 1.1 + + + +Instantiates: + +Test + + + +Status: + +<Work In Progress> + + + + +Detailed Description + + +Property Documentation + +fifth : int + +int +fifth +writable +public +active +unspecified + +fourth : int +int +fourth +writable +public +active +unspecified + +A group of properties sharing a documentation comment. + + +group group +group.first : int + +int +group.first +writable +public +active +unspecified + +group.second : int + +int +group.second +writable +public +active +unspecified + +group.third : int + +int +group.third +writable +public +active +unspecified + +A property group. + + +[read-only] id : int + +int +id +[read-only] + +public +active +unspecified + +A read-only property. + + +[required] name : string + +string +name +writable +required +public +active +unspecified + +Name of the Test. + + + +Attached Property Documentation + +[default: Type.NoType] Type.type : enumeration + +enumeration +Type.type +attached +writable +public +active +unspecified + + + + +Constant +Description + + + + +Type.NoType + + +Nothing + + + + +Type.SomeType + + +Something + + + + + + +Signal Documentation + +completed(int status) +This signal is emitted when the operation completed with status. + +The corresponding handler is onCompleted. + + + +group.created() +This signal is prefixed with group. + +The corresponding handler is group.onCreated. + + + + +Attached Signal Documentation + +configured() +This attached signal is emitted when the type was configured. + +The corresponding handler is onConfigured. + + + + +Method Documentation + +disable() + + +disable + +qmlmethod +disable() +public +active +unspecified + +enable() + +enable + +qmlmethod +enable() +public +active +unspecified + +Enables or disables this type. + + +Type copy(a) +Returns another Type based on a. + + + +Obsolete Members for Type +The following members of QML type Type are deprecated. We strongly advise against using them in new code. + +Obsolete Method Documentation + +deprecatedMethod() +This method is deprecated since 6.2. We strongly advise against using it in new code. +This method has no replacement This is a method that should include information about being deprecated and that it has been so since 6.2 in its docs. + + + + diff --git a/tests/auto/qdoc/generatedoutput/expected_output/docbookext/qml-qdoc-test-yetanotherchild.xml b/tests/auto/qdoc/generatedoutput/expected_output/docbookext/qml-qdoc-test-yetanotherchild.xml new file mode 100644 index 000000000..34264b735 --- /dev/null +++ b/tests/auto/qdoc/generatedoutput/expected_output/docbookext/qml-qdoc-test-yetanotherchild.xml @@ -0,0 +1,44 @@ + + + +YetAnotherChild QML Type +Test +A test project for QDoc build artifacts + +A type inheriting from internal abstract parent. +This type was introduced in Qt 1.1. + + + + +Import Statement + +import QDoc.Test 1.1 + + + +Since: + +Qt 1.1 + + + + +Detailed Description + + +Property Documentation + +prop : int + +int +prop +writable +public +active +unspecified + +Propagated to inheriting type docs. + + + diff --git a/tests/auto/qdoc/generatedoutput/expected_output/docbookext/qml-test-nover-typenoversion.xml b/tests/auto/qdoc/generatedoutput/expected_output/docbookext/qml-test-nover-typenoversion.xml new file mode 100644 index 000000000..87576add4 --- /dev/null +++ b/tests/auto/qdoc/generatedoutput/expected_output/docbookext/qml-test-nover-typenoversion.xml @@ -0,0 +1,41 @@ + + + +TypeNoVersion QML Type +Test +A test project for QDoc build artifacts + +Another QML type documented in a .cpp file. +This type was introduced in Qt 1.1. + + + + +Import Statement + +import Test.NoVer + + + +Since: + +Qt 1.1 + + + +Instantiates: + +TestDerived + + + +Status: + +Tech Preview + + + + +Detailed Description + + diff --git a/tests/auto/qdoc/generatedoutput/expected_output/docbookext/qml-uicomponents-progressbar.xml b/tests/auto/qdoc/generatedoutput/expected_output/docbookext/qml-uicomponents-progressbar.xml new file mode 100644 index 000000000..cd0945ec1 --- /dev/null +++ b/tests/auto/qdoc/generatedoutput/expected_output/docbookext/qml-uicomponents-progressbar.xml @@ -0,0 +1,104 @@ + + + +ProgressBar QML Type +Test +A test project for QDoc build artifacts + +A component that shows the progress of an event. + + + + +Import Statement + +import UIComponents 1.0 + + + + +Detailed Description +A ProgressBar shows the linear progress of an event as its value. The range is specified using the minimum and the maximum values. +The ProgressBar component is part of the UI Components module. +This documentation is part of the UIComponents example. + + +Property Documentation + +color : color + +color +color +writable +public +active +unspecified + +The color of the ProgressBar's gradient. Must bind to a color type. + +See Also +See also + +secondColor + + + + + +maximum : int + +int +maximum +writable +public +active +unspecified + +The maximum value of the ProgressBar range. The value must not be more than this value. + + +minimum : int + +int +minimum +writable +public +active +unspecified + +The minimum value of the ProgressBar range. The value must not be less than this value. + + +secondColor : color + +color +secondColor +writable +public +active +unspecified + +The second color of the ProgressBar's gradient. Must bind to a color type. + +See Also +See also + +color + + + + + +value : int + +int +value +writable +public +active +unspecified + +The value of the progress. + + + diff --git a/tests/auto/qdoc/generatedoutput/expected_output/docbookext/qml-uicomponents-switch.xml b/tests/auto/qdoc/generatedoutput/expected_output/docbookext/qml-uicomponents-switch.xml new file mode 100644 index 000000000..65992be73 --- /dev/null +++ b/tests/auto/qdoc/generatedoutput/expected_output/docbookext/qml-uicomponents-switch.xml @@ -0,0 +1,47 @@ + + + +Switch QML Type +Test +A test project for QDoc build artifacts + +A component that can be turned on or off. + + + + +Import Statement + +import UIComponents 1.0 + + + + +Detailed Description +A toggle switch has two states: an on and an off state. The off state is when the on property is set to false. +The ToggleSwitch component is part of the UI Components module. +This documentation is part of the UIComponents example. + + +Property Documentation + +on : bool + +bool +on +writable +public +active +unspecified + +Indicates the state of the switch. If false, then the switch is in the off state. + + + +Method Documentation + +toggle() +A method to toggle the switch. If the switch is on, the toggling it will turn it off. Toggling a switch in the off position will turn it on. + + + diff --git a/tests/auto/qdoc/generatedoutput/expected_output/docbookext/qml-uicomponents-tabwidget.xml b/tests/auto/qdoc/generatedoutput/expected_output/docbookext/qml-uicomponents-tabwidget.xml new file mode 100644 index 000000000..61644e64d --- /dev/null +++ b/tests/auto/qdoc/generatedoutput/expected_output/docbookext/qml-uicomponents-tabwidget.xml @@ -0,0 +1,77 @@ + + + +TabWidget QML Type +Test +A test project for QDoc build artifacts + +A widget that places its children as tabs. + + + + +Import Statement + +import UIComponents 1.0 + + + + +Detailed Description +A TabWidget places its children as tabs in a view. Selecting a tab involves selecting the tab at the top. +The TabWidget component is part of the UI Components module. +This documentation is part of the UIComponents example. + +Adding Tabs +To add a tab, declare the tab as a child of the TabWidget. +TabWidget { + id: tabwidget + + Rectangle { + id: tab1 + color: &quot;red&quot; + //... omitted + } + Rectangle { + id: tab2 + color: &quot;blue&quot; + //... omitted + } + +} + + + + +Property Documentation + +current : int + +int +current +writable +public +active +unspecified + +The currently active tab in the TabWidget. + + +[read-only] sampleReadOnlyProperty : int + +int +sampleReadOnlyProperty +[read-only] + +public +active +unspecified + +A sample read-only property. A contrived property to demonstrate QDoc's ability to detect read-only properties. +The signature is: +readonly property int sampleReadOnlyProperty: 0 + +Note that the property must be initialized to a value. + + + diff --git a/tests/auto/qdoc/generatedoutput/expected_output/docbookext/test-componentset-example.xml b/tests/auto/qdoc/generatedoutput/expected_output/docbookext/test-componentset-example.xml new file mode 100644 index 000000000..add2bcae1 --- /dev/null +++ b/tests/auto/qdoc/generatedoutput/expected_output/docbookext/test-componentset-example.xml @@ -0,0 +1,55 @@ + + + +QML Documentation Example +Test +A test project for QDoc build artifacts + +Example for documenting QML types. + + +This example demonstrates one of the ways to document QML types. It also generates a warning about a missing example image, on purpose. +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 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. + + +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. +\qmlproperty int anAliasedProperty +An aliased property of type int. + + +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. + + + +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. + + +List of Files +Files: + +List of Files + + +componentset/ProgressBar.qml + +componentset/Switch.qml + +componentset/TabWidget.qml + +componentset/componentset.pro + +componentset/componentset.qml + + + diff --git a/tests/auto/qdoc/generatedoutput/expected_output/docbookext/test-nover-qmlmodule.xml b/tests/auto/qdoc/generatedoutput/expected_output/docbookext/test-nover-qmlmodule.xml new file mode 100644 index 000000000..1cd079200 --- /dev/null +++ b/tests/auto/qdoc/generatedoutput/expected_output/docbookext/test-nover-qmlmodule.xml @@ -0,0 +1,24 @@ + + + +Versionless QML Module +Test +A test project for QDoc build artifacts + +QML Types for the Test module without version. +This module is in Tech Preview state. +This module was introduced in Qt 1.1. + + +This module is in Tech Preview state. +This module was introduced in Qt 1.1. + + + +TypeNoVersion + +Another QML type documented in a .cpp file. + + + + diff --git a/tests/auto/qdoc/generatedoutput/expected_output/docbookext/testcpp-module.xml b/tests/auto/qdoc/generatedoutput/expected_output/docbookext/testcpp-module.xml new file mode 100644 index 000000000..0026854b2 --- /dev/null +++ b/tests/auto/qdoc/generatedoutput/expected_output/docbookext/testcpp-module.xml @@ -0,0 +1,83 @@ + + + +QDoc Test C++ Classes +TestCPP +TestCPP Reference Documentation + +A test module page. +This module was introduced in Qt 2.0. + + +A test module page. +This module was introduced in Qt 2.0. + +Namespaces + + +CrossModuleRef + +Namespace that has documented functions in multiple modules. + + + +TestQDoc + +A namespace. + + + + + +Classes + + +TestQDoc::Test + +A class in a namespace. + + + +TestQDoc::TestDerived + +A derived class in a namespace. + + + + + +Detailed Description + +This is just a test. /* Look, Ma! {I'm made of arguments!} */ + + +Linking to function-like things + + +someFunctionDefaultArg() + + +QDOCTEST_MACRO2() + + +QDOCTEST_MACRO2(int &x) + + +section() + + +section() is a section title + + +open( parenthesis + + +C++11 added std::move(T&& t) + + + +section() + + + + diff --git a/tests/auto/qdoc/generatedoutput/expected_output/docbookext/testqdoc-test.xml b/tests/auto/qdoc/generatedoutput/expected_output/docbookext/testqdoc-test.xml new file mode 100644 index 000000000..06b8f5816 --- /dev/null +++ b/tests/auto/qdoc/generatedoutput/expected_output/docbookext/testqdoc-test.xml @@ -0,0 +1,358 @@ + + + +Test Class +TestQDoc::Test +TestCPP +TestCPP Reference Documentation + +A class in a namespace. +This class was introduced in Qt 2.0. + + + + +Header + +Test + + + +Since + +Qt 2.0 + + + +CMake + +find_package(Qt6 REQUIRED COMPONENTS QDocTest) +target_link_libraries(mytarget PRIVATE Qt6::QDocTest) + + + +qmake + +QT += testcpp + + + +Inherited By + +TestQDoc::TestDerived + + + +Group + +Test is part of testgroupTest C++ Types + + + + + +Detailed Description + + +Member Type Documentation + +Test::SomeType + +SomeType +public +active +unspecified + +A typedef. + + + +Member Function Documentation + +[protected] void Test::overload() +[protected, since Test 1.2] void Test::overload(bool b) +Overloads that share a documentation comment, optionally taking a parameter b. + + +[noexcept default] Test::Test() + +Test + +default +constructor +Test() = default +public +active +unspecified + +Default constructor. + + +void (*)(bool) Test::funcPtr(bool b, const char *s) + +void (*)(bool) +funcPtr + +bool +b + + +const char * +s + +plain +void (*)(bool) funcPtr(bool b, const char *s) +public +active +unspecified + +Returns a pointer to a function that takes a boolean. Uses b and s. + + +void Test::inlineFunction() + + +inlineFunction + +plain +void inlineFunction() +public +active +unspecified + +An inline function, documented using the \fn QDoc command. + + +void Test::methodWithEmDashInItsDocs() + + +methodWithEmDashInItsDocs + +plain +void methodWithEmDashInItsDocs() +public +active +unspecified + +This method has em dashes in its documentation—as you'll find represented by --- in the sources—here and there. The important bit to note is that when passed e.g. to the \c command, the three hyphens are processed as input to the command and not replaced by an em dash. +----------------------------------------------------------------------- +People can still add a bunch of dashes, though, without QDoc replacing them all with a series of em dashes. +—You can also start a new paragraph with an em dash, if you want to. + +See Also +See also + +methodWithEnDashInItsDocs + + + + + +void Test::methodWithEnDashInItsDocs() + + +methodWithEnDashInItsDocs + +plain +void methodWithEnDashInItsDocs() +public +active +unspecified + +This method has en dashes in its documentation – as you'll find represented by -- in the sources – here and there. The important bit to note is that when passed e.g. to the \c command, the two hyphens are processed as input to the command and not replaced by an en dash. This also applies to code blocks, where otherwise, the decrement operator would get completely borked: +for (int i = 42; i &gt; 0; --i) + // Do something cool during countdown. + +...as it would be silly if this would output –i instead of --i. +----------------------------------------------------------------------- +It still allows people to add a bunch of dashes, though, without replacing them all with a series of en dashes. Of course, they might want to use the \hr command instead, like this: +– You can also start a new paragraph with an en dash, if you want to. + +See Also +See also + +methodWithEnDashInItsDocs + + + + + +int Test::someFunction(int, int v = 0) + +int +someFunction + +int + + + +int +v +0 + +plain +int someFunction(int, int v) +public +active +unspecified + +Function that takes a parameter v. Also returns the value of v. + + +void Test::someFunctionDefaultArg(int i, bool b = false) + + +someFunctionDefaultArg + +int +i + + +bool +b +false + +plain +void someFunctionDefaultArg(int i, bool b) +public +active +unspecified + +Function that takes a parameter i and b. + + +[virtual] void Test::virtualFun() + +virtual + +virtualFun + +plain +void virtualFun() +public +active +unspecified + +Function that must be reimplemented. + + +[noexcept default] TestQDoc::Test &Test::operator=(TestQDoc::Test &&other) + +TestQDoc::Test & +operator= + +TestQDoc::Test && +other + +default +move-assign +TestQDoc::Test & operator=(TestQDoc::Test &&other) = default +public +active +unspecified + +Move-assigns other. + + + +Related Non-Members + +bool operator==(const TestQDoc::Test &lhs, const TestQDoc::Test &rhs) + +bool +operator== + +const TestQDoc::Test & +lhs + + +const TestQDoc::Test & +rhs + +plain +bool operator==(const TestQDoc::Test &lhs, const TestQDoc::Test &rhs) +public +active +unspecified + +Returns true if lhs and rhs are equal. + + + +Macro Documentation + +[since Test 1.1] QDOCTEST_MACRO2(int &x) + +QDOCTEST_MACRO2 + +int & +x + +macrowithparams +QDOCTEST_MACRO2(int &x) +public +active +unspecified + +A macro with argument x. +This macro was introduced in Test 1.1. + + + +Obsolete Members for Test +The following members of class Test are deprecated. We strongly advise against using them in new code. + +Obsolete Member Function Documentation + +TestQDoc::Test &Test::operator++() +TestQDoc::Test &Test::operator--() +This function is deprecated. We strongly advise against using it in new code. + + +void Test::anotherObsoleteMember() + + +anotherObsoleteMember + +plain +void anotherObsoleteMember() +public +deprecated +unspecified + +This function is deprecated. We strongly advise against using it in new code. +Use obsoleteMember() instead. + + +void Test::deprecatedMember() + + +deprecatedMember + +plain +void deprecatedMember() +public +deprecated +unspecified + +This function is deprecated since 6.0. We strongly advise against using it in new code. +Use someFunction() instead. + + +void Test::obsoleteMember() + + +obsoleteMember + +plain +void obsoleteMember() +public +deprecated +unspecified + +This function is deprecated. We strongly advise against using it in new code. +Use someFunction() instead. + + + + diff --git a/tests/auto/qdoc/generatedoutput/expected_output/docbookext/testqdoc-testderived.xml b/tests/auto/qdoc/generatedoutput/expected_output/docbookext/testqdoc-testderived.xml new file mode 100644 index 000000000..5b792c60d --- /dev/null +++ b/tests/auto/qdoc/generatedoutput/expected_output/docbookext/testqdoc-testderived.xml @@ -0,0 +1,114 @@ + + + +TestDerived Class +TestQDoc::TestDerived +TestCPP +TestCPP Reference Documentation + +A derived class in a namespace. +This class was introduced in Qt 2.0. + + + + +Header + +TestDerived + + + +Since + +Qt 2.0 + + + +CMake + +find_package(Qt6 REQUIRED COMPONENTS QDocTest) +target_link_libraries(mytarget PRIVATE Qt6::QDocTest) + + + +qmake + +QT += testcpp + + + +Inherits + +TestQDoc::Test + + + + +Detailed Description + + +Member Type Documentation + +[alias] TestDerived::DerivedType + +DerivedType +public +active +unspecified + +An aliased typedef. + + +[alias] TestDerived::NotTypedef + +NotTypedef +public +active +unspecified + +I'm an alias, not a typedef. + + + +Member Function Documentation + +[override virtual] void TestDerived::virtualFun() + +virtual + +virtualFun + +override +plain +void virtualFun() override +public +active +unspecified + +Reimplements: Test::virtualFun(). + + + +Obsolete Members for TestDerived +The following members of class TestDerived are deprecated. We strongly advise against using them in new code. + +Obsolete Member Function Documentation + +[static] void TestDerived::staticObsoleteMember() + +static + +staticObsoleteMember + +plain +void staticObsoleteMember() +public +deprecated +unspecified + +This function is deprecated. We strongly advise against using it in new code. +Static obsolete method. + + + + diff --git a/tests/auto/qdoc/generatedoutput/expected_output/docbookext/testqdoc.xml b/tests/auto/qdoc/generatedoutput/expected_output/docbookext/testqdoc.xml new file mode 100644 index 000000000..7fd926ed1 --- /dev/null +++ b/tests/auto/qdoc/generatedoutput/expected_output/docbookext/testqdoc.xml @@ -0,0 +1,72 @@ + + + +TestQDoc Namespace +TestCPP +TestCPP Reference Documentation + +A namespace. +This namespace was introduced in Qt 2.0. + + + + +Header + +TestCPP + + + +Since + +Qt 2.0 + + + +CMake + +find_package(Qt6 REQUIRED COMPONENTS QDocTest) +target_link_libraries(mytarget PRIVATE Qt6::QDocTest) + + + +qmake + +QT += testcpp + + + + +Detailed Description + +Usage +This namespace is for testing QDoc output. + + + +Classes + +class Test +A class in a namespace. + + +class TestDerived +A derived class in a namespace. + + + +Macro Documentation + +QDOCTEST_MACRO + +QDOCTEST_MACRO + +macrowithoutparams +QDOCTEST_MACRO +public +active +unspecified + + + + diff --git a/tests/auto/qdoc/generatedoutput/expected_output/docbookext/uicomponents-qmlmodule.xml b/tests/auto/qdoc/generatedoutput/expected_output/docbookext/uicomponents-qmlmodule.xml new file mode 100644 index 000000000..f00b3d3f7 --- /dev/null +++ b/tests/auto/qdoc/generatedoutput/expected_output/docbookext/uicomponents-qmlmodule.xml @@ -0,0 +1,34 @@ + + + +UI Components +Test +A test project for QDoc build artifacts + +Basic set of UI components. + + + +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. + + +ProgressBar + +A component that shows the progress of an event. + + + +Switch + +A component that can be turned on or off. + + + +TabWidget + +A widget that places its children as tabs. + + + + diff --git a/tests/auto/qdoc/generatedoutput/testdata/configs/docbook.qdocconf b/tests/auto/qdoc/generatedoutput/testdata/configs/docbook.qdocconf index 68afd29e8..9bd6c7bba 100644 --- a/tests/auto/qdoc/generatedoutput/testdata/configs/docbook.qdocconf +++ b/tests/auto/qdoc/generatedoutput/testdata/configs/docbook.qdocconf @@ -1,6 +1,6 @@ outputformats = DocBook -DocBook.nosubdirs = true -DocBook.outputsubdir = docbook +DocBook.nosubdirs = true +DocBook.outputsubdir = docbook # TODO: DocBook generator has trouble handling shared comment nodes # allow two warnings related to these diff --git a/tests/auto/qdoc/generatedoutput/testdata/configs/docbookext.qdocconf b/tests/auto/qdoc/generatedoutput/testdata/configs/docbookext.qdocconf new file mode 100644 index 000000000..c54eb11c5 --- /dev/null +++ b/tests/auto/qdoc/generatedoutput/testdata/configs/docbookext.qdocconf @@ -0,0 +1,8 @@ +outputformats = DocBook +DocBook.nosubdirs = true +DocBook.outputsubdir = docbookext +DocBook.usedocbookextensions = true + +# 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/docbookext_test.qdocconf b/tests/auto/qdoc/generatedoutput/testdata/configs/docbookext_test.qdocconf new file mode 100644 index 000000000..233bd60bb --- /dev/null +++ b/tests/auto/qdoc/generatedoutput/testdata/configs/docbookext_test.qdocconf @@ -0,0 +1,3 @@ +include(config.qdocconf) +include(test.qdocconf) +include(docbookext.qdocconf) diff --git a/tests/auto/qdoc/generatedoutput/testdata/configs/docbookext_testcpp.qdocconf b/tests/auto/qdoc/generatedoutput/testdata/configs/docbookext_testcpp.qdocconf new file mode 100644 index 000000000..19b2af6a9 --- /dev/null +++ b/tests/auto/qdoc/generatedoutput/testdata/configs/docbookext_testcpp.qdocconf @@ -0,0 +1,3 @@ +include(config.qdocconf) +include(testcpp.qdocconf) +include(docbookext.qdocconf) diff --git a/tests/auto/qdoc/generatedoutput/testdata/configs/docbookext_testqml.qdocconf b/tests/auto/qdoc/generatedoutput/testdata/configs/docbookext_testqml.qdocconf new file mode 100644 index 000000000..36b22b3ad --- /dev/null +++ b/tests/auto/qdoc/generatedoutput/testdata/configs/docbookext_testqml.qdocconf @@ -0,0 +1,3 @@ +include(config.qdocconf) +include(testqml.qdocconf) +include(docbookext.qdocconf) diff --git a/tests/auto/qdoc/generatedoutput/tst_generatedoutput.cpp b/tests/auto/qdoc/generatedoutput/tst_generatedoutput.cpp index 785fad427..ea0c47e1a 100644 --- a/tests/auto/qdoc/generatedoutput/tst_generatedoutput.cpp +++ b/tests/auto/qdoc/generatedoutput/tst_generatedoutput.cpp @@ -29,10 +29,13 @@ private slots: void webXmlFromCppBug80259(); void illformated_documentation(); - // DocBook generator + // DocBook generator (wiht and without extensions) void docBookFromQDocFile(); void docBookFromCpp(); void docBookFromQml(); + void docBookWithExtensionsFromQDocFile(); + void docBookWithExtensionsFromCpp(); + void docBookWithExtensionsFromQml(); // Output format independent tests void autoNavigation(); @@ -342,6 +345,43 @@ void tst_generatedOutput::docBookFromQml() "docbook/qml-int.xml"); } +void tst_generatedOutput::docBookWithExtensionsFromQDocFile() +{ + testAndCompare("testdata/configs/docbookext_test.qdocconf", + "docbookext/qdoctests-qdocfileoutput.xml " + "docbookext/qdoctests-qdocmanuallikefileoutput.xml " + "docbookext/qdoctests-qdocfileoutput-linking.xml " + "docbookext/qdoctests-qdocfileoutput-exhaustive.xml"); +} + +void tst_generatedOutput::docBookWithExtensionsFromCpp() +{ + testAndCompare("testdata/configs/docbookext_testcpp.qdocconf", + "docbookext/testcpp-module.xml " + "docbookext/testqdoc-test.xml " + "docbookext/testqdoc-testderived.xml " + "docbookext/testqdoc.xml"); +} + +void tst_generatedOutput::docBookWithExtensionsFromQml() +{ + testAndCompare("testdata/configs/docbookext_testqml.qdocconf", + "docbookext/test-componentset-example.xml " + "docbookext/uicomponents-qmlmodule.xml " + "docbookext/qdoc-test-qmlmodule.xml " + "docbookext/test-nover-qmlmodule.xml " + "docbookext/qml-qdoc-test-abstractparent.xml " + "docbookext/qml-qdoc-test-child.xml " + "docbookext/qml-qdoc-test-yetanotherchild.xml " + "docbookext/qml-qdoc-test-doctest.xml " + "docbookext/qml-qdoc-test-type.xml " + "docbookext/qml-test-nover-typenoversion.xml " + "docbookext/qml-uicomponents-progressbar.xml " + "docbookext/qml-uicomponents-switch.xml " + "docbookext/qml-uicomponents-tabwidget.xml " + "docbookext/qml-int.xml"); +} + void tst_generatedOutput::autoNavigation() { // Same expected files as htmlFromQdocFile, but with auto-generated navigation links -- cgit v1.2.1