diff options
| author | Paul Wicking <paul.wicking@qt.io> | 2019-04-08 11:53:49 +0200 |
|---|---|---|
| committer | Paul Wicking <paul.wicking@qt.io> | 2019-07-26 10:06:16 +0200 |
| commit | a449cb8c4a7fd46c33e4977a91c5097676ad5c39 (patch) | |
| tree | 54a60801b6ac19c8bbd6b0799f43ed2da026e383 /tests | |
| parent | c825330078a994f4ecd76569b80f47538f674610 (diff) | |
QDoc: Add smoke test for QML component output
This change adds a simple smoke test using the QML component
documentation example as test data.
Task-number: QTBUG-71168
Change-Id: Ieb4af0ff69e044cf3eed10297db62edaf066d933
Reviewed-by: Edward Welbourne <edward.welbourne@qt.io>
Diffstat (limited to 'tests')
11 files changed, 106 insertions, 4 deletions
diff --git a/tests/auto/qdoc/qmlcomponentoutput/componentset/ProgressBar.qml b/tests/auto/qdoc/generatedoutput/componentset/ProgressBar.qml index 2a40cc488..2a40cc488 100644 --- a/tests/auto/qdoc/qmlcomponentoutput/componentset/ProgressBar.qml +++ b/tests/auto/qdoc/generatedoutput/componentset/ProgressBar.qml diff --git a/tests/auto/qdoc/qmlcomponentoutput/componentset/Switch.qml b/tests/auto/qdoc/generatedoutput/componentset/Switch.qml index db9616b69..db9616b69 100644 --- a/tests/auto/qdoc/qmlcomponentoutput/componentset/Switch.qml +++ b/tests/auto/qdoc/generatedoutput/componentset/Switch.qml diff --git a/tests/auto/qdoc/qmlcomponentoutput/componentset/TabWidget.qml b/tests/auto/qdoc/generatedoutput/componentset/TabWidget.qml index 07fd40db9..07fd40db9 100644 --- a/tests/auto/qdoc/qmlcomponentoutput/componentset/TabWidget.qml +++ b/tests/auto/qdoc/generatedoutput/componentset/TabWidget.qml diff --git a/tests/auto/qdoc/qmlcomponentoutput/componentset/componentset.pro b/tests/auto/qdoc/generatedoutput/componentset/componentset.pro index 5b44737c2..5b44737c2 100644 --- a/tests/auto/qdoc/qmlcomponentoutput/componentset/componentset.pro +++ b/tests/auto/qdoc/generatedoutput/componentset/componentset.pro diff --git a/tests/auto/qdoc/qmlcomponentoutput/componentset/uicomponents.qdoc.sample b/tests/auto/qdoc/generatedoutput/componentset/uicomponents.qdoc.sample index 0c6d187ed..0c6d187ed 100644 --- a/tests/auto/qdoc/qmlcomponentoutput/componentset/uicomponents.qdoc.sample +++ b/tests/auto/qdoc/generatedoutput/componentset/uicomponents.qdoc.sample diff --git a/tests/auto/qdoc/qmlcomponentoutput/examples.qdoc b/tests/auto/qdoc/generatedoutput/examples.qdoc index 7c780eca8..7c780eca8 100644 --- a/tests/auto/qdoc/qmlcomponentoutput/examples.qdoc +++ b/tests/auto/qdoc/generatedoutput/examples.qdoc diff --git a/tests/auto/qdoc/generatedoutput/expected_output/test-componentset-example.html b/tests/auto/qdoc/generatedoutput/expected_output/test-componentset-example.html new file mode 100644 index 000000000..40c874a3c --- /dev/null +++ b/tests/auto/qdoc/generatedoutput/expected_output/test-componentset-example.html @@ -0,0 +1,49 @@ +<?xml version="1.0" encoding="UTF-8"?> +<!DOCTYPE html> +<html lang="en"> +<head> + <meta http-equiv="Content-Type" content="text/html; charset=utf-8" /> +<!-- examples.qdoc --> + <title>QML Documentation Example | Test</title> +</head> +<body> +<div class="sidebar"> +<div class="toc"> +<h3><a name="toc">Contents</a></h3> +<ul> +<li class="level1"><a href="#qml-class">QML Class</a></li> +<li class="level1"><a href="#properties-signals-handlers-and-methods">Properties, Signals, Handlers, and Methods</a></li> +<li class="level2"><a href="#internal-documentation">Internal Documentation</a></li> +<li class="level1"><a href="#qml-types-with-c-implementation">QML Types with C++ Implementation</a></li> +</ul> +</div> +<div class="sidebar-content" id="sidebar-content"></div></div> +<h1 class="title">QML Documentation Example</h1> +<span class="subtitle"></span> +<!-- $$$componentset-description --> +<div class="descr"> <a name="details"></a> +<p>This example demonstrates one of the ways to document QML types.</p> +<p>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 <a href="uicomponents-qmlmodule.html">UI Components</a> module.</p> +<p>The uicomponents.qdoc file generates the overview page for the <a href="uicomponents-qmlmodule.html">UI Components</a> module page.</p> +<p>The generated documentation is available in the <a href="uicomponents-qmlmodule.html">UI Components</a> module.</p> +<a name="qml-class"></a> +<h4 id="qml-class">QML Class</h4> +<p>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 <code>UIComponents</code> module.</p> +<p>QDoc uses the \brief command to place a basic description when listing the types.</p> +<a name="properties-signals-handlers-and-methods"></a> +<h4 id="properties-signals-handlers-and-methods">Properties, Signals, Handlers, and Methods</h4> +<p>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.</p> +<p>To document the type of a <i>property alias</i>, you must use the \qmlproperty command to specify the data type.</p> +<pre class="cpp">\qmlproperty <span class="type">int</span> anAliasedProperty +An aliased property of type <span class="type">int</span><span class="operator">.</span></pre> +<a name="internal-documentation"></a> +<h5 id="internal-documentation">Internal Documentation</h5> +<p>You may declare that a documentation is for internal use by placing the \internal command after the beginning QDoc comment <code>/*</code>. QDoc will prevent the internal documentation from appearing in the public API.</p> +<p>If you wish to omit certain parts of the documentation, you may use the \omit and \endomit command.</p> +<a name="qml-types-with-c-implementation"></a> +<h4 id="qml-types-with-c-implementation">QML Types with C++ Implementation</h4> +<p>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.</p> +</div> +<!-- @@@componentset --> +</body> +</html> diff --git a/tests/auto/qdoc/generatedoutput/expected_output/uicomponents-qmlmodule.html b/tests/auto/qdoc/generatedoutput/expected_output/uicomponents-qmlmodule.html new file mode 100644 index 000000000..87a0d45b5 --- /dev/null +++ b/tests/auto/qdoc/generatedoutput/expected_output/uicomponents-qmlmodule.html @@ -0,0 +1,20 @@ +<?xml version="1.0" encoding="UTF-8"?> +<!DOCTYPE html> +<html lang="en"> +<head> + <meta http-equiv="Content-Type" content="text/html; charset=utf-8" /> +<!-- examples.qdoc --> + <title>UI Components | Test</title> +</head> +<body> +<div class="sidebar"><div class="sidebar-content" id="sidebar-content"></div></div> +<h1 class="title">UI Components</h1> +<span class="subtitle"></span> +<!-- $$$UIComponents-description --> +<div class="descr"> <a name="details"></a> +<p>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.</p> +<p>This module is part of the <a href="test-componentset-example.html#">UIComponents</a> example.</p> +</div> +<!-- @@@UIComponents --> +</body> +</html> diff --git a/tests/auto/qdoc/generatedoutput/test.qdocconf b/tests/auto/qdoc/generatedoutput/test.qdocconf index 47ed6a919..fe51e1c67 100644 --- a/tests/auto/qdoc/generatedoutput/test.qdocconf +++ b/tests/auto/qdoc/generatedoutput/test.qdocconf @@ -2,10 +2,7 @@ project = Test description = "A test project for QDoc build artifacts" moduleheader = -headerdirs = . -sourcedirs = . - -sources.fileextensions = *.qdoc +sources = qdoctests-outputfromqdocfiles.qdoc macro.beginqdoc = "\\c {/*!}" macro.endqdoc = "\\c */" diff --git a/tests/auto/qdoc/generatedoutput/testqml.qdocconf b/tests/auto/qdoc/generatedoutput/testqml.qdocconf new file mode 100644 index 000000000..769c3d627 --- /dev/null +++ b/tests/auto/qdoc/generatedoutput/testqml.qdocconf @@ -0,0 +1,10 @@ +project = Test +description = "A test project for QDoc build artifacts" +moduleheader= +outputdir = ./html + +exampledirs = . +sources.fileextensions = \ + examples.qdoc + +macro.begincomment = "\\c{/*}" diff --git a/tests/auto/qdoc/generatedoutput/tst_generatedoutput.cpp b/tests/auto/qdoc/generatedoutput/tst_generatedoutput.cpp index 0e6f4445c..be08f5784 100644 --- a/tests/auto/qdoc/generatedoutput/tst_generatedoutput.cpp +++ b/tests/auto/qdoc/generatedoutput/tst_generatedoutput.cpp @@ -38,6 +38,7 @@ private slots: void init(); void htmlFromCpp(); + void htmlFromQml(); private: QScopedPointer<QTemporaryDir> m_outputDir; @@ -125,6 +126,31 @@ void tst_generatedOutput::htmlFromCpp() compareLineByLine(expectedFile, actualFile); } + +void tst_generatedOutput::htmlFromQml() +{ + const QStringList arguments = { + "--outputdir", + m_outputDir->path(), + QFINDTESTDATA("testqml.qdocconf") + }; + + if (!runQDocProcess(arguments)) + QFAIL("Running QDoc failed. See output above."); + + const QStringList files{ + "test-componentset-example.html", + "uicomponents-qmlmodule.html"}; + + for (const auto &file : files) { + QString expectedPath = "/expected_output/" + file; + QString expectedFile(QFINDTESTDATA(expectedPath)); + QString actualFile(m_outputDir->path() + "/" + file); + + compareLineByLine(expectedFile, actualFile); + } +} + QTEST_APPLESS_MAIN(tst_generatedOutput) #include "tst_generatedoutput.moc" |