QDoc's `\l` command accepts QDoc macro as the link target, and will
expand the macro in place before linking to the target. As multi-word
targets must be wrapped in curly braces, macros that expand to multiple
words (i.e. a string that contains spaces) must also be wrapped in curly
braces.
This commit adds a test case to QDoc's end-to-end test that verifies
QDoc's ability to link to macro expansions using the `\l` command. The
test serves as documentation of this functionality and prevents future
regressions when modifying QDoc's link processing.
Change-Id: I29efc9b419569946e5dcf7d64dfea3319944092a
Reviewed-by: Topi Reiniö <topi.reinio@qt.io>
(cherry picked from commit d94abd53078a6e12a6c5fad3e2adb71338dd2080)
Reviewed-by: Qt Cherry-pick Bot <cherrypick_bot@qt-project.org>
(cherry picked from commit 9d148b283e5ffbf19c04da8ac9a0e7d052ca9013)
While reviewing the code in QDoc's HTMLGenerator class, I found some
minor whitespace issues that I fixed as I passed by. This patch is the
result of that cleanup.
Task-number: QTBUG-92109
Change-Id: I3084f7376c98db05092311686db77f4c271c3dd6
Reviewed-by: Topi Reiniö <topi.reinio@qt.io>
(cherry picked from commit 5f4961df7d69bd67742120da3964a4c3348f8f6d)
Reviewed-by: Qt Cherry-pick Bot <cherrypick_bot@qt-project.org>
(cherry picked from commit 7fbabe718636da509f722e7b794759bd53cefb62)
`git-review` is a command line tool for interacting with Gerrit.
Some IDEs offer support for this tool, either natively or through
plugins. The tool relies on a configuration file, .gitreview. Adding
this configuration file to our repositories simplifies initial setup
for contributors that use the tool directly or through their IDE of
choice.
The configuration file adds a remote called 'gerrit'. This is the
default for the tool, and also the name set for
codereview.qt-project.org by Qt's `init-repository` script. Thus,
the configuration should work seamlessly alongside other repository
helpers.
Task-number: QTBUG-132604
Change-Id: I1a1896ed0fd676101940dadcee5e1641440ec7c2
Reviewed-by: Samuel Gaist <samuel.gaist@idiap.ch>
(cherry picked from commit 8bf44c671cde33abf097770e3e2acfcd00aac99a)
Reviewed-by: Qt Cherry-pick Bot <cherrypick_bot@qt-project.org>
(cherry picked from commit 3485806d8075e0b6ecfb25b0b79303bb1206ad30)
Both the base class (Aggregate) and the inherited class return a
`QmlTypeNode*`, so there's no type conversion needed. Drop the
`static_cast<>()` call.
Task-number: QTBUG-130646
Change-Id: Iae3a0f4e720605c3f64bee0ceac60b6de9a6925e
Reviewed-by: Topi Reiniö <topi.reinio@qt.io>
(cherry picked from commit 2874cbaa84bfd73052f02f1fb3a1686455c8c63d)
Reviewed-by: Qt Cherry-pick Bot <cherrypick_bot@qt-project.org>
Since `156aec7209ec92f93116b556b480381d8e4a63a6`, QDoc no longer makes
use of the `CLANG_RESOURCE_DIR` environment variable, so it's pointless
to set it in `CMakeLists.txt`.
Task-number: QTBUG-130282
Change-Id: I03df860e6b869172056309cd390d3f089c351a46
Reviewed-by: Joerg Bornemann <joerg.bornemann@qt.io>
(cherry picked from commit 12a3bedafda2632b6a3849faa9f1001540d85d79)
Reviewed-by: Qt Cherry-pick Bot <cherrypick_bot@qt-project.org>
QDoc's `ClangCodeParser` passes a set of default arguments to Clang
when interfacing with it. These arguments include the C++ standard,
`-D` options, etc. Among these is
`-I/path/expanded/from/$CLANG_RESOURCE_DIR`. This path is generated by
CMake at build time and may therefore be incorrect if the binary is
moved to a different system; reports indicate that this indeed is an
issue in Yocto builds.
[ChangeLog][QDoc] QDoc no longer passes the contents of the
`CLANG_RESOURCE_DIR` environment variable as an include path when
interfacing with Clang.
Task-number: QTBUG-130282
Change-Id: I3642a7e67f8de175491e3d7626821a66eb8dd86d
Reviewed-by: Joerg Bornemann <joerg.bornemann@qt.io>
(cherry picked from commit 156aec7209ec92f93116b556b480381d8e4a63a6)
Reviewed-by: Paul Wicking <paul.wicking@qt.io>
Reviewed-by: Topi Reiniö <topi.reinio@qt.io>
Due to upstream changes in LLVM 19, QDoc fails to compile when linked
against Clang libraries from this version of LLVM. Three issues arise;
- Two cases of passing an argument of wrong type to a function.
- One case of accessing a non-existing member of an enumeration.
One upstream change (see [0]) is responsible for two of the issues:
- `get_expression_as_string()` is modified such that it correctly
obtains the parameter type when calling
`get_fully_qualified_type_name()`, by appending
`.getArgument().getAsType()` to the call to `getDefaultArgument()`.
- `get_default_value_initializer_as_string()` is modified such that it
correctly passes the source expression to
`get_expression_as_string()`, by appending `.getSourceExpression()`
to the call to `getDefaultArgument()`.
Both of these changes are is incompatible with QDoc built against
Clang libraries from earlier versions of LLVM, and are therefore
wrapped in #if-ery.
Finally, LLVM 19 drops a value used in QDoc from the enumeration
`clang::TemplateName::Qualified`, see [1]. The enum value `Fully` is
removed without replacement. The enum is left with two values,
`AsWritten` and `None`. QDoc is modified such that it relies on the
former of the two. This change doesn't cause any change in output from
QDoc when built against Clang libraries from LLVM 17 and 18, and the
change is therefore not wrapped in #if-ery.
[0] - https://github.com/llvm/llvm-project/commit/e42b799bb28815431f2c5a95f7e13fde3f1b36a1
[1] - https://github.com/llvm/llvm-project/commit/9c4a716c12920
Done-with: Khem Raj <raj.khem@gmail.com>
Fixes: QTBUG-128644
Change-Id: I34fbb46cf28b5676b4adda5e563d6d59fc40f602
Reviewed-by: Luca Di Sera <luca.disera@qt.io>
Reviewed-by: Topi Reiniö <topi.reinio@qt.io>
(cherry picked from commit 4a368a06afa5929d8674d2e94c2d7cbd6ad85d4e)
Reviewed-by: Qt Cherry-pick Bot <cherrypick_bot@qt-project.org>
For compatibility reasons, QDoc carries a custom implementation of
`llvm-project.git/clang/lib/AST/QualTypeNames.cpp`. When QDoc is built
against Clang libraries from LLVM 19, a segmentation fault occurs when
generating the documentation for the Qt 3D module as part of a qt5.git
super-module documentation build.
The segmentation fault is the result of a `nullptr` being passed to
`clang::TypeName::getFullyQualifiedNestedNameSpecifier` for the
`Scope` parameter.
Upon investigation, it became clear that two changes have been made
upstream to the implementation QDoc carries a customized version of,
one of which adds a `nullptr` check. Due to the small footprint of
both changes, this patch applies both of them to QDoc's
`clang/AST/QualTypeNames.h`:
- The upstream change 16832eb58563f77d917198ad9f86db1c2ee162c9 adds a
`nullptr` check, see https://github.com/llvm/llvm-project/pull/94084
for details.
- The upstream change 35bfbb3b21e9874d03b730e8ce4eb98b1dcd2d28
replaces `dyn_cast_or_null<T>(foo)` with `dyn_cast<T>(foo)` for
never-null arguments. See
https://github.com/llvm/llvm-project/commit/35bfbb3b21e9874d03b730e8ce4eb98b1dcd2d28
for details.
The changes apply also when QDoc is built against Clang libraries from
LLVM 17 and 18, with both end-to-end tests passing. Given the nature of
the changes, this means these adaptations do not require being wrapped
in `#if LIBCLANG_VERSION_MAJOR` checks.
Fixes: QTBUG-128926
Change-Id: I5863ca213a35042ed325971b42de2bc1e86c6457
Reviewed-by: Luca Di Sera <luca.disera@qt.io>
Reviewed-by: Topi Reiniö <topi.reinio@qt.io>
(cherry picked from commit a2f478b20f369132de1e67b30716d5f070d7bf80)
Reviewed-by: Qt Cherry-pick Bot <cherrypick_bot@qt-project.org>
The implementation of QDoc's `Config` class includes a struct,
`ConfigStrings`. This struct is a wrapper for static QStrings, and
is a Singleton-like monostate container that provides a globally
accessible, single set of configuration options across the entire
application.
This struct defines the member field `ALIAS`. However, this field is
never initialized with a default value, never set with a value read
from a `qdocconf` file, and never read during QDoc's execution. Hence,
the field is deemed unused and unnecessary, and thus removed.
Change-Id: I0eb29a72b26c8c3210401780f98eb133d5257f14
Reviewed-by: Topi Reiniö <topi.reinio@qt.io>
(cherry picked from commit e11cc4801dda53a943f0ecf4ed82b1d878565173)
Reviewed-by: Qt Cherry-pick Bot <cherrypick_bot@qt-project.org>
This amends commit `d31d4735e21d5a8338c305b8e801a07572a93db6`.
The implementation in the aforementioned commit employed a string
comparison to ascertain whether the declared return type was
`auto`. This string comparison is performed twice per case; once for
the function declaration that represents the input to the `\fn`
command, and once for the return type set on the related
`FunctionNode`.
This patch replaces said string comparisons by obtaining the necessary
information from Clang's API, reducing the number of string
allocations and avoiding the two string comparisons entirely.
Task-number: QTBUG-126537
Change-Id: I8a10be7f4eb2754f5c50207b254d977fba2f24ea
Reviewed-by: Topi Reiniö <topi.reinio@qt.io>
(cherry picked from commit 9da54f24387f4f290fa1f6ea479e25719dc21b15)
Reviewed-by: Qt Cherry-pick Bot <cherrypick_bot@qt-project.org>
At the build system level, QDoc continues to define
`QDOC2_COMPAT`. This define is unused, and has been so for several
years. Commit `d259c70d47d0dbf2fb49b6fdb52b1283e8a69a41` removed the
definition from the qmake configuration; however, the port to CMake
overlapped this and accidentally re-introduced the definition with
commit `9d5887fbc6fe0b20c4faf7eb42f1b71130e95120`.
Commit `a40749199be276aa89fcb4c171c4943a581d91de` removed code that
required the definition of `QDOC2_COMPAT`. Since that commit, the
definition has been unused.
This change seeks to remove this define for good, as it does
absolutely nothing, and hasn't for many years.
Change-Id: I00c618a805faf7bac5cc52d0ce6d1c927865ea44
Reviewed-by: Topi Reiniö <topi.reinio@qt.io>
(cherry picked from commit 213a613244cbbccaaf22f969e73d16052254f593)
Reviewed-by: Qt Cherry-pick Bot <cherrypick_bot@qt-project.org>
While bulk changing use of the `\instantiates` command to the new
`nativetype` command, the entries in the QDoc manual for
`\instantiates` were changed on accident. This lead to a confusing
statement in the documentation:
"The \nativetype command is deprecated since Qt 6.8.
Use \nativetype instead".
This change corrects the command name in the documentation.
Task-number: QTBUG-128216
Change-Id: Ib1f42d2166c1ccfb231885ba21bf35c3d0752194
Reviewed-by: Andreas Eliasson <andreas.eliasson@qt.io>
(cherry picked from commit 3a0419d51a5cfa32b02ecf5ff156ddaf2eb1cb02)
Reviewed-by: Qt Cherry-pick Bot <cherrypick_bot@qt-project.org>
The QDoc manual contains a code snippet that shows how to employ the
`\include` command. This snippet uses the command in a mock "Core
Features" page. The documentation goes on to provide a link to the
file as it would be generated by QDoc, to provide a visual example.
Both the file name and page title are problematic, as there's nothing
that indicates that this is an example and not a page that should
describe QDoc's core features. Furthermore, as this page is indexed by
search engines, it may be presented in a prominent position in search
results. This includes, and is likely not limited to, searching for
the string "core features" in the search box on doc.qt.io.
Remove the file and the line that references it, as it is deemed
unnecessary.
Fixes: QTBUG-128411
Pick-to: 6.7
Change-Id: Ie7d7949588f4b1f93fd55a4e4467d9f98a7a6c75
Reviewed-by: Kai Köhne <kai.koehne@qt.io>
(cherry picked from commit a2dcb23e55551330f92c9c56d4db6a07331c2209)
Reviewed-by: Qt Cherry-pick Bot <cherrypick_bot@qt-project.org>
The QDoc command `\tableofcontents` was rendered useless by a change
more than a decade ago. Remove the use of `\tableofcontents` as it
serves no purpose, and ensure that the surrounding context still makes
sense for the reader, by removing preceding text that refers to a
non-existing table of contents, such as `Contents:`.
Task-number: QTBUG-128173
Change-Id: I9187d7b9da88c431f0eac33922bb1a2b3499a0f6
Reviewed-by: Paul Wicking <paul.wicking@qt.io>
Reviewed-by: Safiyyah Moosa <safiyyah.moosa@qt.io>
(cherry picked from commit 3453d1fe533772f8e0f253702ae27011841b62a3)
Reviewed-by: Qt Cherry-pick Bot <cherrypick_bot@qt-project.org>
In its internal representation of a documentation set, QDoc may apply
"code markers" to certain strings. These markers serve as tokens that
allow QDoc to distinguish code from plain text.
When generating DocBook output, QDoc removes code markers from certain
`Atom`s before passing them to the XML writer for output. However,
certain escape characters end up being passed to the writer, which in
turn escapes them again. The result is output such as:
<db:programlisting language="cpp">{
&quot;FirstName&quot;: &quot;John&quot;,
&quot;LastName&quot;: &quot;Doe&quot;,
&quot;Age&quot;: 43,
&quot;Address&quot;: {
&quot;Street&quot;: &quot;Downing Street 10&quot;,
&quot;City&quot;: &quot;London&quot;,
&quot;Country&quot;: &quot;Great Britain&quot;
},
&quot;Phone numbers&quot;: [
&quot;+44 1234567&quot;,
&quot;+44 2345678&quot;
]
}
</db:programlisting>
QDoc's `Generator` class contains the method `plainCode`, which
replaces certain HTML escape entity names with their corresponding
character. Pass the string through this method to strip the escape
character entities from the string before passing the string to the
XML writer. Update the output in the two end-to-end output tests that
are affected by this change in behavior.
Fixes: QTBUG-126994
Change-Id: Iccdb86abd9061f257dc248f1d6313a839784450e
Reviewed-by: Thibaut Cuvelier <cuvelier.thibaut@gmail.com>
Reviewed-by: Joerg Bornemann <joerg.bornemann@qt.io>
(cherry picked from commit 4960d72240f06abd4ce0af5149142ea10659aa47)
Reviewed-by: Qt Cherry-pick Bot <cherrypick_bot@qt-project.org>
Since the implementation of the `\nativetype`-command in QDoc,
the `\instantiates`-command is deprecated. Replace the use of the
deprecated command in favor of its replacement.
Task-number: QTBUG-128216
Change-Id: I3c9f7ad5bad535716e435ff44aa2cf6408965701
Reviewed-by: Venugopal Shivashankar <Venugopal.Shivashankar@qt.io>
(cherry picked from commit 2606ee5a9e58471879d05a598adf41bf9f9e1ddd)
Reviewed-by: Qt Cherry-pick Bot <cherrypick_bot@qt-project.org>
lupdate passes options to Clang when it calls the compiler. Among
these options is the flag `-mno-sse`. This flag is intended to disable
the generation of SIMD instructions for SSE, and is applicable to x86
and x86_64 architectures. The option doesn't exist for other
architectures. When lupdate is linked against `libclang` built for
ARM(64), its compiler invocation thus fails.
Wrap the compiler option in a check for the underlying system
architecture such that it is passed to clang only if the system
architecture is a match. Exclude systems running macOS from this check,
as macOS provides Rosetta 2 which provides a way to run X86 code on
ARM. A comment is modified for added precision, and its contents
reflowed to stay within conventional column bounds.
Task-number: QTBUG-127751
Change-Id: If91d9b5fa45d5836953d9ea8bff9670851caff06
Reviewed-by: Joerg Bornemann <joerg.bornemann@qt.io>
(cherry picked from commit 333baa13eb6cb8d549793fbd47786cefad5b496e)
Reviewed-by: Qt Cherry-pick Bot <cherrypick_bot@qt-project.org>
When documenting a C++ function using the `\fn` command, QDoc expects
the fully qualified type as part of the signature passed to that
command. If a function is declared and defined in source using the
`auto` keyword to let the compiler deduce the type, QDoc correctly
generates `auto` as the type for the function in most cases. However,
if the type is a template specialization, QDoc's `ClangCodeParser`
will set the type to the compiler deduced type instead of
`auto`. Though technically correct, this may depart from the author's
intention, and may expose implementation details of an API that are
meant to be hidden. In the case of Qt, this may mean exposing the
`QtPrivate` namespace, which client code shouldn't use directly.
This patch seeks to resolve this issue and thus allow an author to
specify `auto` as the return type passed to QDoc's `\fn` command:
* Add a test project that makes use of `auto` as return type in
documentation.
* Change the type of `FunctionNode::m_returnType` from `QString` to
`QPair<QString, std::optional<QString>>`, such that it may hold an
optional second value.
* Update `FunctionNode::setReturnType` and `FunctionNode::returnsBool`
to operate on the first element of `FunctionNode::m_returnType`.
* Add `FunctionNode::declaredReturnType` as a getter for the second
element of `FunctionNode::m_returnType`.
* Add `FunctionNode::returnTypeString` as a convenience getter for the
return type, which returns the second element of
`FunctionNode::m_returnType` if it is set, otherwise the first
element.
* Modify `ClangCodeParser::visitFnSignature` to set the declared
return type on the `FunctionNode` if the node's return type differs
from that which is declared in the `\fn`-command, and if the
declared return type is `auto`.
* Modify `CppCodeMarker::markedUpSynopsis` and such that it calls the new
convenience getter for the return type string. Make the same changes
to call sites in `DocBookGenerator`.
[ChangeLog][QDoc] QDoc now respects the author's intent better, in that it outputs `auto` as the return type of functions that are documented with `auto` as their return type.
Fixes: QTBUG-126537
Change-Id: I5fa18effca2ee69937a2d66763213948c09e5e8c
Reviewed-by: Topi Reiniö <topi.reinio@qt.io>
(cherry picked from commit d31d4735e21d5a8338c305b8e801a07572a93db6)
Reviewed-by: Qt Cherry-pick Bot <cherrypick_bot@qt-project.org>
This typo was staring me in the face and I couldn\'t not fix it.
Task-number: QTBUG-126537
Change-Id: Ic2cbcb13f4fababe795d9020d9b7873a67b67c68
Reviewed-by: Topi Reiniö <topi.reinio@qt.io>
(cherry picked from commit 7be97899aba422cd13f78d1cfde5bb10961b2dcc)
Reviewed-by: Qt Cherry-pick Bot <cherrypick_bot@qt-project.org>
Drop a space character, and update test data accordingly.
Task-number: QTBUG-127617
Change-Id: I5966c02d814888baed361a8a374392af9a519780
Reviewed-by: Topi Reiniö <topi.reinio@qt.io>
(cherry picked from commit 1f56de58b29c09c5cd7072099fadb2cfdb8528cb)
Reviewed-by: Qt Cherry-pick Bot <cherrypick_bot@qt-project.org>
In API documentation for C++ and QML, QDoc generates a `requisites`
table that lists information about, for example, the header to include
to gain access to a class or namespace, CMake instructions, etc. As
the intention is to provide this as copy-pasta, make the information
stand out visually by wrapping it in the `code` html element, to
ensure it's rendered with a monospace font face.
Extend the CSS class for the table with the new identifier
`requisites`, such that the table can be styled with ease.
Fixes: QTBUG-127617
Change-Id: I78f31317feb2245e69bb2703484dcc95318627a9
Reviewed-by: Topi Reiniö <topi.reinio@qt.io>
(cherry picked from commit eb3d903cffa4d1610812a86e201a774f4430ef4d)
Due to an upstream change [0], QDoc no longer generates the `noexcept`
specifier for compiler generated member functions when QDoc is linked
against LLVM 18. The issue has been addressed previously for the
`tst_validateQdocOutputFiles` test [1], by modifying the impacted test
data such that documentation isn't generated for such functions in
tests, thus ensuring that QDoc generates identical output for the test
projects when linked against both LLVM 17 and 18.
Due to an oversight, the duplicate test data in `tst_generatedOutput`
was not modified accordingly. This change addresses that mistake.
[0] https://github.com/llvm/llvm-project/pull/69688
[1] 9f2cbfc5bc405d55ef5a066b5fc81895b513618d (qttools.git)
Task-number: QTBUG-123130
Change-Id: I72da94b49144649d787158894ae1bf09589fc7f3
Reviewed-by: Luca Di Sera <luca.disera@qt.io>
(cherry picked from commit 274a589bb7bfb218fdfe7f98d2e0125aa1cddb74)
Reviewed-by: Topi Reiniö <topi.reinio@qt.io>
Due to an upstream change [0], QDoc no longer generates the `noexcept`
specifier for compiler generated member functions when QDoc is linked
against LLVM 18. This change modifies the test projects for the output
validation test such that documentation isn't generated for such
functions in tests, thus ensuring that QDoc generates identical output
for the test projects when linked against both LLVM 17 and 18.
[0] https://github.com/llvm/llvm-project/pull/69688
Task-number: QTBUG-123130
Change-Id: I0d1fd48be08ec4beb11e1d74ae574ddb2c914a4a
Reviewed-by: Topi Reiniö <topi.reinio@qt.io>
(cherry picked from commit 9f2cbfc5bc405d55ef5a066b5fc81895b513618d)
Add link to https://download.qt.io/linguist_releases/ and mention that
the installer that can be obtained from there is for Windows and works
with Qt 6.
Fixes: QTBUG-101378
Fixes: QTBUG-97510
Pick-to: 6.7 6.5
Change-Id: I3a5573484f4388f92feb86cb48c740555cbb99d1
Reviewed-by: Leena Miettinen <riitta-leena.miettinen@qt.io>
(cherry picked from commit aa624705de7a425b8059271e8c84aa9d6767ce33)
Reviewed-by: Qt Cherry-pick Bot <cherrypick_bot@qt-project.org>
Due to ASan's use of sigaltstack, it can crash with deallocation
errors if instrumenting binaries that also use sigaltstack (directly
or transitively). As LLVM has its own sigaltstack, this has caused
integration failures in COIN (see related Jira issues).
This is a known issue, see e.g:
https://github.com/google/sanitizers/issues/849https://github.com/KDE/kdevelop/commit/e306f3e39aba37b606dadba195fa5b7b73816f8f
Modify the test binary such that it sets or extends the `ASAN_OPTIONS`
environment variable for QDoc's process environment, to avoid crash in
ASan. Promote the existing QProcessEnvironment to a static that is
shared between the `initTestCase` and `runQDocProcess` member
functions, to avoid the cost of repeatedly creating the QPE object.
Fixes: QTBUG-126116
Task-number: QTBUG-111580
Change-Id: I25c7baed9ccec14aaad0c47512b58118a3a91d84
Reviewed-by: Topi Reiniö <topi.reinio@qt.io>
(cherry picked from commit 31835b4c9f31ffdf17202d1bf257d68f1adb0ce1)
Reviewed-by: Qt Cherry-pick Bot <cherrypick_bot@qt-project.org>
Since the introduction of the new '\nativetype' command and the
subsequent deprecation of the '\instantiates' command, the notion of a
"qml element" that belongs to a `ClassNode` is made redundant. The only
external use of the related API in `ClassNode` is in
`Tree::resolveCppToQmlLinks`. This change replaces the call to
`setQmlElement` with a call to `insertQmlNativeType`, which is the
corresponding setter for the new QDoc command. This ensures full
feature parity between the new and old commands, and leaves the
setter, getter, and data member in `ClassNode` unused, and therefore
removed.
Task-number: QTBUG-125368
Change-Id: If0b541844f27fe4455ad1ae27c82d471611e2e81
Reviewed-by: Topi Reiniö <topi.reinio@qt.io>
ClassNode::findQmlBaseNode is a recursive function whose only use is
in the recursive call to itself. Drop the code as it's unused.
Task-number: QTBUG-125368
Change-Id: I39354c3e3990c58786bfc9bc9829b43a60650570
Reviewed-by: Topi Reiniö <topi.reinio@qt.io>
With the introduction of the '\nativetype' command, QDoc now has an
improved mechanism for documenting what a QML type is called in
C++. The new command was introduced with the explicit aim to replace
the old, and thus this patch deprecates the latter and replaces its
use in QDoc's documentation and tests.
The old command is kept for compatibility reasons, but now delegates
to the new command internally. This means QDoc will generate the same
output for both commands until the now deprecated '\instantiates'
command is removed.
Modify the QDoc manual accordingly, and promote `\nativetype` where
suitable.
[ChangeLog][QDoc][Deprecation] The '\instantiates' command is
deprecated and will be removed in a future version of QDoc. Use the
new '\nativetype' command instead.
Task-number: QTBUG-125368
Change-Id: Ia14ef9636ec45c6c5d71d739342963b903f2c557
Reviewed-by: Topi Reiniö <topi.reinio@qt.io>
QDoc supports the use of a command, `\instantiates`, which is meant to
be used to describe what a QML type is called in C++, and generate
links between the C++ documentation and QML documentation. This
command causes some confusion for users, both authors and
readers, as its name describes a concept in programming that goes
beyond "this type is called [Foo] in C++|QML". The output from QDoc is
equally responsible for this confusion.
To avoid causing a breaking change, a new command `\nativetype`, is
introduced as a means to replace the `\instantiates` command, while
allowing for a transition period before the latters removal.
The new command works mostly as the old one, with the following
notable differences:
- Terminology in output is simplified to be as exact as possible. With
new command, QDoc will generate "In C++"/"In QML" as part of the
requisites table for C++ class and QML type documentation.
- The new command correctly accounts for the fact that multiple QML
types can have the same C++ type as their native type. In such
cases, any one QML type will only list one C++ class under "In C++",
while the C++ class will contain a list of all corresponding QML
types.
This change includes an extension of the QDoc output validation test
which exercises the new behavior, as well as documentation
that (hopefully) helps make it clear what this command does.
[ChangeLog][QDoc][General] The new 'nativetype' command supercedes the
'instantiates' command. New documentation should use the new command.
Fixes: QTBUG-125368
Change-Id: I7891d1a9ff8dca3742b60d7bdce32e4d830808a5
Reviewed-by: Topi Reiniö <topi.reinio@qt.io>
The description in the documentation gets the relationship backwards
and is confusing. This patch seeks to clarify the behavior of the
'\instantiates' command.
Pick-to: 6.7 6.5 6.2
Task-number: QTBUG-125368
Change-Id: Ibe227a4bd65dd370060ef818dba9cae76eb195c5
Reviewed-by: Topi Reiniö <topi.reinio@qt.io>
Spotted in review of something else. It's unused, get rid of it.
Change-Id: I30717c78e781daf79206003547de9eba4770fee4
Reviewed-by: Thibaut Cuvelier <cuvelier.thibaut@gmail.com>
Reviewed-by: Topi Reiniö <topi.reinio@qt.io>
The documentation for a QML type, e.g. ```Foo```, can contain the
'\instantiates' command, which takes the name of a C++ class as its
argument:
\instantiates QFoo
This command establishes a relationship between the nodes that
represent the QML type and C++ class internally to the given QDoc
execution. This relationship is described in the synopsis generated in
the documentation for both the QML type (e.g. "Instantiates: QFoo")
and the C++ class (e.g. "Instantiated by: Foo". In QDoc's node
hierarchy, this relationship exists as a `ClassNode *classNode` for
`QmlTypeNode`s, and as a `QmlTypeNode *qmlElement` for
`ClassNode`s.
The design allows for a unilateral many-to-one relationship, in that
multiple `QmlTypeNode`s can reference the same `ClassNode`, but the
`ClassNode` can only refer to one QML element. As a consequence of
this design choice, when QDoc encounters the '\instantiates' command
with a given C++ class as argument more than once, it replaces the QML
element relationship for the C++ class. This happens without a warning
or other kind of feedback to the user, and may therefore cause
unexpected and surprising output.
QDoc's current implementation does not lend itself to easily change
this into a one-to-many or many-to-many relationship without increased
technical risk. This change introduces a new warning to QDoc in the
instances where this occurs, and extends the QDoc warning
documentation accordingly. The behavior is otherwise kept unchanged,
as QDoc cannot determine the order in a deterministic manner.
Task-number: QTBUG-125076
Change-Id: I5bfc46099f0c4a2f3bf221209c03046859f48a60
Reviewed-by: Topi Reiniö <topi.reinio@qt.io>
Add information about configuring output formats and location
information to the qdocconf section for new tests, as this can be
surprising or easily forgotten about.
Task-number: QTBUG-119500
Change-Id: Ie6fb7b8eabfa4483d777c0438755d8b93f651c48
Reviewed-by: Topi Reiniö <topi.reinio@qt.io>
Ensure that test data is properly separated from test configuration
and expected output by moving test data into a `src`
subdirectory. This has an added benefit of ensuring uniform structure
for all test cases.
Task-number: QTBUG-119500
Change-Id: Iea8bc1d84f1b80b6b7f77a23330793d4cfa78891
Reviewed-by: Topi Reiniö <topi.reinio@qt.io>
When QDoc generates the output for a page, the page may contain
multiple `\sectionN` commands. These commands take a string as input,
which becomes the title for the following section of text. If a
section title is duplicated, they must have a unique `id` HTML
attribute to be correctly linkable entities.
This is achieved by extending `Tree::populateTocSectionTargetMap`.
This method iterates over the Atoms that represent the table of
contents for a given Doc for a Node. Ensure that the TOC consists of
uniquely identifiable entries in case of name collisions, such that
QDoc can generate correct output for all such references in a given
document. For section titles that collide on a given page, unique
section references are generated for all but the first instance.
These unique references are then appended to the
Atom::SectionHeadingLeft that follows the Atom being processed, for
later retrieval.
Tree::refForAtom is modified such that, for both Atom::SectionLeft
and Atom::SectionHeadingLeft, the behavior is ensured to be the same.
This is made possible by the fact that these Atoms appear in tandem.
For Atoms of type Atom::SectionHeadingLeft, return the second entry
of its stringlist if its length is two, as that indicates that a
unique reference has been appended to the Atom being processed.
Modify the generator subclasses to account for the new behavior, by
calling the modified Tree::refForAtom to obtain the correct reference
for the Atom being generated.
Add E2E test case for unique anchors for duplicate section titles.
Fixes: QTBUG-122261
Change-Id: I53b4871c31224210b5e9a7cbf3c5df7dec6df8a2
Reviewed-by: Topi Reiniö <topi.reinio@qt.io>
Turn the conditional into a switch statement, to prepare for upcoming
changes to the method. Add an assertion on the Node* argument. Update
method documentation.
Task-number: QTBUG-122261
Change-Id: I63952e59eef43d0c62669f6e84d8a9a900457474
Reviewed-by: Topi Reiniö <topi.reinio@qt.io>
`Tree::resolveTargets` is responsible for ensuring the maps
`m_nodesByTargetRef` and `m_nodesByTargetTitle` are correct. The
implementation details for the various tasks clutter reading the
algorithm.
Extract the code responsible for adding targets (defined with QDoc's
\target command) associated with the Node being processed to the maps.
Task-number: QTBUG-122261
Change-Id: If0ab471003267ab41a229ac4bf81e0eae882ad81
Reviewed-by: Topi Reiniö <topi.reinio@qt.io>
`Tree::resolveTargets` is responsible for ensuring the maps
`m_nodesByTargetRef` and `m_nodesByTargetTitle` are correct. The
implementation details for the various tasks clutter reading the
algorithm.
Extract the code that adds keywords (defined by QDoc's \keyword
command) associated with the Node being processed to the maps.
Task-number: QTBUG-122261
Change-Id: I5d11b8d64680046f57468871b682868318be04ac
Reviewed-by: Topi Reiniö <topi.reinio@qt.io>
`Tree::resolveTargets` is responsible for ensuring the maps
`m_nodesByTargetRef` and `m_nodesByTargetTitle` are correct. The
implementation details for the various tasks clutter reading the
algorithm.
Extract the code that is responsible for populating the maps for
each section in the table of contents of the Node being processed.
Task-number: QTBUG-122261
Change-Id: I72b9698b2b848bd58eade95981aae2144b536fdc
Reviewed-by: Topi Reiniö <topi.reinio@qt.io>
`Tree::resolveTargets` is responsible for ensuring the maps
`m_nodesByTargetRef` and `m_nodesByTargetTitle` are correct. The
implementation details for the various tasks clutter reading the
algorithm.
Extract the code that's responsible for ensuring that each unique
PageNode is stored in the `m_pageNodesByTitle` under its title and
delegate to the new method from the call site. As part of the
extraction, replace a manual loop with a call to the std::any_of
algorithm.
Task-number: QTBUG-122261
Change-Id: I391da5bc38d64e6a737a0c77874c9683cce50f48
Reviewed-by: Topi Reiniö <topi.reinio@qt.io>
Add `Atom::append` which appends its argument to the list of strings
held by the Atom.
Task-number: QTBUG-122261
Change-Id: I415a0a151b20cb4e39125fd078279641720e6b44
Reviewed-by: Topi Reiniö <topi.reinio@qt.io>
Tree::refForAtom is arguably ill-placed in Tree.
For now, turn it into a public static, in preparation for
changes in HTMLGenerator that will require access to it.
Task-number: QTBUG-122261
Change-Id: I17bf0207e0b61d832006ceb28c8553407f466d64
Reviewed-by: Topi Reiniö <topi.reinio@qt.io>
The method `Atom::appendString` operates on a member string list.
However, it doesn't append a string to the list; it concatenates its
argument with the first string in the list. Rename the method to
reduce ambiguity and pave the way for a method that actually appends a
string to the list of strings.
Task-number: QTBUG-122261
Change-Id: I68fa9401e2180c49121f1d2c9853ca149c98cd76
Reviewed-by: Topi Reiniö <topi.reinio@qt.io>
Substitute C-style cast with static_cast, and apply curly braces to an
else clause that was in violation of Qt's code style.
Change-Id: Ifd5cbb56c91837da4886d60340ed580a984daa9f
Reviewed-by: Topi Reiniö <topi.reinio@qt.io>
The `properties` test was already moved from `tst_generatedOutput`
into `tst_validateQdocOutputFiles`. This change modifies the latter
such that it includes the source for this particular test case, and
removes the case from the former.
Task-number: QTBUG-119500
Pick-to: 6.7
Change-Id: Iff241b15ca428ff5077a8bd050ad0a9891eb3031
Reviewed-by: Topi Reiniö <topi.reinio@qt.io>
QDoc now has better test infrastructure. Move a trivial test project
from `tst_generatedOutput` into `tst_validateQdocOutputFiles` and
adjust expected output accordingly.
Task-number: QTBUG-119500
Pick-to: 6.7
Change-Id: I122d2aa901d7b8640df3506b89fa559b2742064d
Reviewed-by: Topi Reiniö <topi.reinio@qt.io>
QDoc's new `tst_validateQdocOutputFiles` provides better
infrastructure for testing output generated by QDoc than
`tst_generatedOutput` does. Move the test data for the `dontdocument`
test case of the latter into the `comprehensiveproject` of the former,
and modify the expected output accordingly.
Task-number: QTBUG-119500
Pick-to: 6.7
Change-Id: Ib8ca88ff2e7545c60920b0042c6d8b944ea54722
Reviewed-by: Topi Reiniö <topi.reinio@qt.io>
With the advent of QDoc's `tst_validateQdocOutputFiles` test, we now
have a better way to test QDoc's generated output. One of the test
cases in the new test represents a rather comprehensive documentation
project. This project was adopted from `tst_generatedOutput`, where it
is known as `TestCPP`.
This change removes a configuration file from `tst_generatedOutput`
and adapts the aforementioned documentation project such that the
behavior remains tested. Expected output files are modified
accordingly.
Task-number: QTBUG-119500
Pick-to: 6.7
Change-Id: Ifa3c7c4fcbfd05c9ed45f989286fabe79995ad4b
Reviewed-by: Topi Reiniö <topi.reinio@qt.io>
QDoc maintains a slightly modified version of the Clang header
`QualTypeNames.h`. Due to an upstream change [0] that changes an enum
into an enum class and renames a value that's used in the
aforementioned header, QDoc fails to compile against Clang 18.
This patch introduces a preprocessor conditional check for the major
version of `libclang` and defines the old symbol name if Clang is of a
version where the symbol has been renamed.
[0] - https://github.com/llvm/llvm-project/commit/4ad2ada5216ee2bb3c334a3233a9ab51f2521b82
Fixes: QTBUG-123109
Pick-to: 6.7
Change-Id: I0fa916a201d963c5f23d87d73105b23fe55719ea
Reviewed-by: Qt CI Bot <qt_ci_bot@qt-project.org>
Reviewed-by: Topi Reiniö <topi.reinio@qt.io>
When generating documentation, QDoc may overwrite files that exist in
the output directory. This behavior is wanted; previously QDoc warned
for each overwrite, making the warning count between multiple
documentation builds not representable. However, users rely on QDocs
traditional warning output and are unlikely to notice debug log
messages.
This change makes QDoc issue a warning when obtaining a file handle for
an output file if that file is known to have been generated previously
in the current execution. It also introduces a new environment variable
`QDOC_ALL_OVERWRITES_ARE_WARNINGS`, to allow the enforcement of QDoc's
past behavior of unconditionally warning instead of debug logging these
events.
The QDoc manual is updated accordingly.
Fixes: QTBUG-121437
Pick-to: 6.7 6.6 6.5
Change-Id: I834027201197039bb4591e633bf72845e8a4343c
Reviewed-by: Topi Reiniö <topi.reinio@qt.io>
Ensure that state isn't changed if the requirements for
COMMAND_QTCMAKEPACKAGE are satisfied.
Pick-to: 6.7 6.6 6.5
Change-Id: I791c8e323dd430efcbeb448e76a27e2ffe305b3f
Reviewed-by: Topi Reiniö <topi.reinio@qt.io>
QDoc provides a way to document CMake instructions by way of the
`\qtcmakepackage` command. This command is restricted such that it can
only be used at the module level (in other words, in the same comment
that contains the \module command). The command injects the module name
in the CMake instructions that are generated in the header table of
each class reference page that belongs to said module. For most of Qt's
APIs, this works fine. However; there are certain APIs that are
"semi-public", in the sense that they're publically documented while
the symbols belong to a private Qt library (e.g. CorePrivate,
GuiPrivate, etc.). In such cases, the automatically generated
documentation is incorrect.
This patch introduces a new command `\qtcmaketargetitem`. This command
lets users override the target part of the content that is generated
for the `find_package()` CMake instructions. It must be used in
conjunction with the pre-existing `\qtcmakepackage` command.
Fixes: QTBUG-121991
Task-number: QTBUG-121855
Task-number: QTBUG-109214
Change-Id: Ia3ea99d08cd63cdc2f82f2220b6cb5b82557fce1
Reviewed-by: Topi Reiniö <topi.reinio@qt.io>
This change moves the `testtemplate` test project from QDoc's
`tst_generatedOutput` to `tst_validateQdocOutputFiles`. The latter is
a data-driven test and better suited for the type of test performed
with this documentation project.
The move involves the following changes:
- Modify the .qdocconf-file to align with the pattern in other test
projects; output formats and output directories.
- Move the expected output files from `tst_generatedOutput`.
- Remove the case for `templateParameters` in
`tst_generatedoutput.cpp`.
Task-number: QTBUG-119500
Change-Id: I9da4f0ec60297e6150347002c243069c694ca5b2
Reviewed-by: Topi Reiniö <topi.reinio@qt.io>
Since 0f409aca96a6b51271cf86edef948a7981195cf4 (qtbase), QDoc has
generated a .qhp.sha1 file. The purpose of this file was to serve
as an identifier that something in the .qhp file changed, for the
purpose of using the .qhp file as a search index.
However, until 473fbb4869, this has
not worked cross-platform, negatively impacting the usefulness of
this feature. Furthermore, there are several types of changes that
do not affect the contents of a .qhp file. That implies that the
usefulness of this hash file is questionable. Finally, obtaining
a SHA1 checksum for the .qhp files is trivial on all three of the
major desktop platforms: use the tool `sha1sum1` on Linux or Mac,
or `CertUtil` on Windows.
Upon further inquiry, it has become evident that the existence of
this file is largely unknown and, indeed, not used anywhere in Qt.
Therefore, this change removes the code reponsible for generating
the .qhp.sha1 files, as well as the QCryptographicHash include.
The commit that introduced this method also `#include`d QDebug,
which is not used in the class. Remove that include as well. This
essentially makes this a revert of the patch that introduced the
feature; as QDoc moved from qtbase.git since then, that part of
the history doesn't belong to qttools.git, effectively enforcing
a new commit instead of a simple revert.
[ChangeLog][QDoc] QDoc no longer generates .qhp.sha1 hash files.
Fixes: QTBUG-121919
Change-Id: I0ad34650109ae03a7f1c3858d31c5027657ab996
Reviewed-by: Topi Reiniö <topi.reinio@qt.io>
Reviewed-by: Jarek Kobus <jaroslaw.kobus@qt.io>
While moving the `testcpp` test project from `tst_generatedOutput` to
the new data-driven `tst_validateQdocOutputFiles` test for QDoc, it
became apparent that several test projects/test configurations
essentially did the same work, with trivial differences, such as adding
an output format, enabling DocBook extensions, etc.
While moving the `testcpp` test project and it's related projects seemed
like a good first step, it quickly became clear that the `tagfiles` test
project already contained essentially the same source files, and was
only missing the output format specific variations and QHP
configuration. After unifying that and building the two projects,
After consolidating the test data for the `testcpp` project, it's clear
that the projects are duplicates:
[testdata]$ diff -qr testcpp tagfiles
Only in tagfiles/expected/html: testtagfile.tags
Only in tagfiles/expected/webxml: testtagfile.tags
Only in tagfiles: tagfiles.qdocconf
Only in testcpp: testcpp.qdocconf
Therefore, merge them all into the `tagfiles` project. Finally, rename
the `tagfiles` test project to give it a more descriptive name.
In the end, this allows dropping the following test cases from
`tst_generatedOutput`:
- htmlFromQml
- webXmlFromCpp
- webXmlFromQml
- docBookFromCpp
- docBookFromQml
- docBookWithExtensionsFromCpp
- docBookWithExtensionsFromQml
- examplesManifestXmlAndQhp
Task-number: QTBUG-119500
Change-Id: Icd59844dc3e4bd96b50105f24559c5746f885673
Reviewed-by: Topi Reiniö <topi.reinio@qt.io>
QDoc can generate Qt Help Project files (`.qhp`-files) through its
`HelpProjectWriter` interface. When it does, it also generates a
`.sha1` file for the generated `.qhp` file. The SHA1 hash it generates
on Windows differs from that it generates on other platforms. This
issue was uncovered when restructuring QDoc's tests for the files it
generates.
Upon investigating the problem, the initial hypothesis was that it was
possibly caused by differing line endings on different platforms. This
theory led to the discovery of a forum.qt.io discussion about a similar
problem:
https://forum.qt.io/topic/124177/qcryptographichash-results-mismatches/3
The forum discussion suggests dropping the `QFile::Text` flag when
opening the file for writing. Indeed, the documentation for
`QIODeviceBase::Text` (the implementation of said flag) states that
"When writing, the end-of-line terminators are translated
to the local encoding, for example '\r\n' for Win32."
This means that on Windows, the `QFile::Text` flag can cause line
ending conversions when writing files. Dropping that flag when opening
the output file ensures that the data is written without any automatic
line ending conversions, thus the result should be consistent across
different platforms.
This means QDoc must open the hashFile in binary mode by not passing
the `QFile::Text` flag. The reason for this is that, on Windows, the
`QFile::Text` flag can cause line ending conversions when reading or
writing text files.
Validating the fix is challenging, as `HelpProjectWriter` isn't covered
by any unit tests. However; the change that follows this makes use of
the QHP-generating capabilities of QDoc in a test, and serves to
validate this fix.
Fixes: QTBUG-121850
Task-number: QTBUG-119500
Pick-to: 6.7 6.6 6.5
Change-Id: I9c3c2242c7698e1b7bc031dd33cdbd305d96c713
Reviewed-by: Qt CI Bot <qt_ci_bot@qt-project.org>
Reviewed-by: Topi Reiniö <topi.reinio@qt.io>
This change moves the `templatedcallables` test project from QDoc's
`tst_generatedOutput` to `tst_validateQdocOutputFiles`. The latter is
a data-driven test and better suited for the type of test performed
with this documentation project.
The move involves the following changes:
- Modify the .qdocconf-file to align with the pattern in other test
projects; output formats and output directories.
- Move the expected output files from `tst_generatedOutput`.
- Remove the case for `templatedCallables` in
`tst_generatedoutput.cpp`.
Task-number: QTBUG-119500
Change-Id: I382012244997a478edce463aa2b152e5f836d841
Reviewed-by: Topi Reiniö <topi.reinio@qt.io>
This change moves the `scopedenum` test project from QDoc's
`tst_generatedOutput` to `tst_validateQdocOutputFiles`. The latter is
a data-driven test and better suited for the type of test performed
with this documentation project.
The move involves the following changes:
- Modify the .qdocconf-file to align with the pattern in other test
projects; output formats and output directories.
- Move the expected output files from `tst_generatedOutput`.
- Remove the case for `scopedEnum` in
`tst_generatedoutput.cpp`.
Task-number: QTBUG-119500
Change-Id: I0965292953e03dc46b97b0f6d909964f7e1c5d26
Reviewed-by: Topi Reiniö <topi.reinio@qt.io>
This change moves the `tableaftervalue` test project from QDoc's
`tst_generatedOutput` to `tst_validateQdocOutputFiles`. The latter is
a data-driven test and better suited for the type of test performed
with this documentation project.
The move involves the following changes:
- Modify the .qdocconf-file to align with the pattern in other test
projects; output formats and output directories.
- Move the expected output files from `tst_generatedOutput`.
- Remove the case for `tableAfterValue` in
`tst_generatedoutput.cpp`.
Task-number: QTBUG-119500
Change-Id: I057ea271beb4a1cf9496208fbb6117e009cbeb01
Reviewed-by: Topi Reiniö <topi.reinio@qt.io>
This change moves the `tagfiles` test project from QDoc's
`tst_generatedOutput` to `tst_validateQdocOutputFiles`. The latter is
a data-driven test and better suited for the type of test performed
with this documentation project.
The move involves the following changes:
- Modify the .qdocconf-file to align with the pattern in other test
projects; output formats and output directories.
- Move the expected output files from `tst_generatedOutput`.
- Remove the case for `testTagFile` in
`tst_generatedoutput.cpp`.
Task-number: QTBUG-119500
Change-Id: I6384ada9b480a1bf6a4473cffc6a7e60da406c1b
Reviewed-by: Topi Reiniö <topi.reinio@qt.io>
When generating example documentation with DocBook or WebXML as output
format, if `url.examples` isn't set, QDoc attempts to generate
individual pages for each file that's part of the example project. This
can cause QDoc to generate file names that are a canonicalized version
of the path to the file on the system where the documentation is
generated.
The issue was discovered when extending the `tagfiles` test project
such that it shall also generate DocBook and WebXML output. Replacing
calls to `ResolvedFile::get_path()` with `ResolvedFile::get_query()`
in the respective `generateExampleFilePage` implementations avoids
using the canonicalized path to the file as filename, and thus
resolves the issue.
Task-number: QTBUG-119500
Fixes: QTBUG-121774
Change-Id: I09cc400a017328d77428e592213e6506c8cf4161
Reviewed-by: Topi Reiniö <topi.reinio@qt.io>
This change moves the `headerfile` test project from QDoc's
`tst_generatedOutput` to `tst_validateQdocOutputFiles`. The latter is
a data-driven test and better suited for the type of test performed
with this documentation project.
The move involves the following changes:
- Modify the .qdocconf-file to align with the pattern in other test
projects; output formats and output directories.
- Move the expected output files from `tst_generatedOutput`.
- Remove the case for `headerFile` in
`tst_generatedoutput.cpp`.
Task-number: QTBUG-119500
Change-Id: I7f57eadb9e1097805b95d2e1438385e98e5a1568
Reviewed-by: Topi Reiniö <topi.reinio@qt.io>
This change moves the `usingdirective` test project from QDoc's
`tst_generatedOutput` to `tst_validateQdocOutputFiles`. The latter is
a data-driven test and better suited for the type of test performed
with this documentation project.
The move involves the following changes:
- Modify the .qdocconf-file to align with the pattern in other test
projects; output formats and output directories.
- Move the expected output files from `tst_generatedOutput`.
- Remove the case for `usingDirective` in
`tst_generatedoutput.cpp`.
Task-number: QTBUG-119500
Change-Id: I6fef9b919436e6307ce51eabbb1272fef7af05cb
Reviewed-by: Topi Reiniö <topi.reinio@qt.io>
This change moves the `outputfromqdocfiles` test project from QDoc's
`tst_generatedOutput` to `tst_validateQdocOutputFiles`. The latter is
a data-driven test and better suited for the type of test performed
with this documentation project.
This move is more invasive than those that precede it, in that the test
project is subject to several test cases in `tst_generatedOutput`, that
serve multiple purposes. Of particular interest is how the test project
exercises QDoc's `if(defined)` directive. To achieve test coverage
parity, while at the same time simplify the test project structure, part
of the test is duplicated, and the configuration files for both
resulting cases are consolidated. In addition;
- Merge output format specific configuration from multiple .qdocconf
files and set their `outputsubdir` such that it aligns with the
pattern in other test projects.
- Also move the expected output files from `tst_generatedOutput`.
- Remove the cases for all involved configurations in
`tst_generatedoutput.cpp`.
Task-number: QTBUG-119500
Change-Id: I7868f1935b90f10312671db95c03fffe24c13e75
Reviewed-by: Topi Reiniö <topi.reinio@qt.io>
For some reason, there was no newline before the pragma once directive.
Pick-to: 6.7
Fixes: QTBUG-121563
Change-Id: I6346e79a470fe85e3f8488d5453b9066ae5302e4
Reviewed-by: Topi Reiniö <topi.reinio@qt.io>
QDoc's generated output test contains multiple configuration files
that generate documentation from the same source files. This change
moves the configuration and source files such that they reside in a
shared directory, `testdata/outputfromqdocfiles`. The configuration
files, as well as the test itself, is updated with the new location.
Task-number: QTBUG-119500
Change-Id: If4f8cb36a6b37e6bc1c41d2bf5905d3cab0dc0eb
Reviewed-by: Topi Reiniö <topi.reinio@qt.io>
QDoc's `generatedOutput` test contains multiple test cases that
essentially all generate the same sources, but for different output
formats. This change copies the contents of the configuration file
`testdata/configs/docbook` into the configuration files that include
said file. The purpose of this change is to decouple the
interdependencies between configuration files to make it easier to
migrate these test projects into the new `validateQdocOutputFiles`
test.
Task-number: QTBUG-119500
Change-Id: Id374faee6c8595cc691ad7454b8eb5784d239575
Reviewed-by: Topi Reiniö <topi.reinio@qt.io>
This change moves the `globalfunc` test project from QDoc's
`tst_generatedOutput` to `tst_validateQdocOutputFiles`. The latter is
a data-driven test and better suited for the type of test performed
with this documentation project.
The move involves the following changes:
- Modify `outputsubdir` to align with the pattern in other test
projects.
- Rename the .qdocconf to match the containing directory's name, such
that the test will pick it up.
- Also move the expected output files from `tst_generatedOutput`.
- Remove the case for `testGlobalFunctions` in
`tst_generatedoutput.cpp`.
Task-number: QTBUG-119500
Change-Id: Ie18bb28176a6271b18f887db9a3e484a55a3dacd
Reviewed-by: Topi Reiniö <topi.reinio@qt.io>
This change moves the `bug80259` test project from QDoc's
`tst_generatedOutput` to `tst_validateQdocOutputFiles`. The latter is
a data-driven test and better suited for the type of test performed
with this documentation project.
The move involves the following changes:
- Modify `outputsubdir` to align with the pattern in other test
projects.
- Rename the .qdocconf to match the containing directory's name, such
that the test will pick it up.
- Move the WebXML configuration into the main configuration file.
- Remove the redundant configuration file for generating WebXML.
- Also move the expected output files from `tst_generatedOutput`.
- Remove the cases for `bug80259` in
`tst_generatedoutput.cpp`.
Task-number: QTBUG-119500
Change-Id: Ife9577b859066780c842a039ac0dc8bc157759c8
Reviewed-by: Topi Reiniö <topi.reinio@qt.io>
This change moves the `proxypage` test project from QDoc's
`tst_generatedOutput` to `tst_validateQdocOutputFiles`. The latter is
a data-driven test and better suited for the type of test performed
with this documentation project.
The move involves the following changes:
- Modify `outputsubdir` to align with the pattern in other test
projects.
- Also move the expected output files from `tst_generatedOutput`.
- Remove the case for `proxyPage` in
`tst_generatedoutput.cpp`.
Task-number: QTBUG-119500
Change-Id: I1dcf628adec884c1542fb31628fd22d55f75ac25
Reviewed-by: Topi Reiniö <topi.reinio@qt.io>
This change moves the `modulestate` test project from QDoc's
`tst_generatedOutput` to `tst_validateQdocOutputFiles`. The latter is
a data-driven test and better suited for the type of test performed
with this documentation project.
The move involves the following changes:
- Modify `outputsubdir` to separate the output for the formats the
test generates.
- Also move the expected output files from `tst_generatedOutput`.
- Remove the case for `modulestateCommand` in
`tst_generatedoutput.cpp`.
Task-number: QTBUG-119500
Change-Id: I233a94546fea6761d58b457a99c54e9e89067922
Reviewed-by: Topi Reiniö <topi.reinio@qt.io>
This change moves the `cxx20` test project from QDoc's
`tst_generatedOutput` to `tst_validateQdocOutputFiles`. The latter is
a data-driven test and better suited for the type of test performed
with this documentation project.
The move involves the following changes:
- Modify `outputsubdir` to separate the output for the formats the
test generates.
- Also move the expected output files from `tst_generatedOutput`.
- Remove the case for `orderingCategoryCommand` in
`tst_generatedoutput.cpp`.
Task-number: QTBUG-119500
Change-Id: Ie20a61b236e91bb087901cfc39f0827ca008328c
Reviewed-by: Topi Reiniö <topi.reinio@qt.io>
This change moves the `illformatted_documentation` test project from
QDoc's `tst_generatedOutput` to `tst_validateQdocOutputFiles`. The
latter is a data-driven test and better suited for the type of test
performed with this documentation project.
The move involves the following changes:
- Add `outputsubdir` for the formats the test generates.
- Also move the expected output files from `tst_generatedOutput`.
- Remove the case for `illformattedDocumentation` in
`tst_generatedoutput.cpp`.
Task-number: QTBUG-119500
Change-Id: Icba817f4aa95d27e94806b7f30ed2df4cb384355
Reviewed-by: Topi Reiniö <topi.reinio@qt.io>
This change moves the `trailing_backslashes` test project from QDoc's
`tst_generatedOutput` to `tst_validateQdocOutputFiles`. The latter is a
data-driven test and better suited for the type of test performed with
this documentation project.
The move involves the following changes:
- Rename the qdocconf file to match the containing directory's name,
as that's a requirement for the test to pick it up.
- Change the configured `outputsubdir` name for each generator, such
that the output is separated for each.
- Also move the expected output files from `tst_generatedOutput`.
- Remove the case for `trailingBackslashes` in
`tst_generatedoutput.cpp`.
Task-number: QTBUG-119500
Change-Id: I26813e8b493a8ce784a7bcfba2bbe4a986ffc66b
Reviewed-by: Topi Reiniö <topi.reinio@qt.io>
Modifications to QDoc may impact the output it generates. While some
such changes may be highly specific, the introduction of a new command,
for example, other such changes may have a much broader scope. The
test that validates QDoc's output files is vulnerable to such changes,
and doesn't have a convenient way to update the expected content for
all of its various test projects in a consistent manner.
This patch modifies tst_validateQdocOutputFiles such that the test
itself can replace the contents of the `expected` directory for its
`testdata` contents. It does so by checking if an environment variable,
`QDOC_REGENERATE_TESTDATA`, is set. If it is, the test will use the
`expected` directory as output directory for each test project, instead
of generating into a temporary directory. The `expected` directory and
contents is recursively deleted before QDoc runs. After running QDoc,
the test skips the comparison and verification steps. Finally, this
change updates the `README.md` for the test with instruction on how to
regenerate expected content for all tests.
Task-number: QTBUG-119500
Change-Id: Ie06b2b4f485504d2acce11420eed82e1cdf2d221
Reviewed-by: Topi Reiniö <topi.reinio@qt.io>
Reviewed-by: Axel Spoerl <axel.spoerl@qt.io>
This change moves the test project from tst_generatedOutput to
tst_validateQdocOutputFiles, removes expected output files from
the former, and adds expected output files to the latter. The
code that calls the test is removed from tst_generatedoutput.cpp.
Task-number: QTBUG-119500
Change-Id: I9fe60b9b3cc3361892b74f1eee4f5002db271fbb
Reviewed-by: Topi Reiniö <topi.reinio@qt.io>
Replace the inclusion of `testqml.qdocconf` in the configuration files
that include it by copying its content verbatim. This is a requirement
to make all test configuration files self-contained.
Task-number: QTBUG-119500
Change-Id: I270434a55e96eb30fcfb6f6eaedfd8aff170f0c1
Reviewed-by: Topi Reiniö <topi.reinio@qt.io>
Move the contents of `testcpp.qdocconf` into the configuration files
that include it. This is required to make the configuration files
self-contained.
As most of the receiving configuration files specify HTML
format-specific settings, that part is omitted when copying.
Task-number: QTBUG-119500
Change-Id: Icf42651b853fec8a5116a15eb142f76c5e9f2c14
Reviewed-by: Topi Reiniö <topi.reinio@qt.io>
This change removes the shared configuration `config.qdocconf` from the
testdata for QDoc's `tst_generatedOutput`. The purpose is to ensure the
configuration for each test is self-contained.
The change involves copying the contents of `config.qdocconf` into
multiple configuration files that depend on it, as well as removing the
`include(config.qdocconf)` line from these. However, some of these
configurations also contain overriding configuration. In those cases,
the contents of `config.qdocconf` aren't copied verbatim, which means
some lines may be dropped in favor of existing content in the receiving
configuration file.
The contents of `config.qdocconf` is copied verbatim into the following
configuration files in `testdata`:
- config/docbook_test.qdocconf
- config/docbook_testqml.qdocconf
- config/docbookext_test.qdocconf
- config/testcpp.qdocconf
- config/testglobals.qdocconf
- config/tocnavigation.qdocconf
- config/usingdirective.qdocconf
- indexlinking/indexlinking.qdocconf
- non_ascii_character_input/non_ascii_character_input.qdocconf
HTML-specific configuration is dropped from `config.qdocconf` when
copying its contents into the following configuration files. Some also
see other minor adjustments:
- config/webxml_test.qdocconf
- config/headerfile.qdocconf
- config/noautolist.qdocconf
- config/docbookext_testqml.qdocconf; kept receiving warninglimit
- cxx20/cxx20.qdocconf
- crossmodule/crossmodule.qdocconf
- proxypage/proxypage.qdocconf
- line_comments/line_comments.qdocconf; also removed a comment
- modulestate/modulestate.qdocconf
- tables/table-after-value.qdocconf
- templatedcallables/templatedcallables.qdocconf
- trailing_backslashes/trailingbackslashes.qdocconf; kept the receiving
warning limit
The following keep the HTML-specific changes but are modified as
indicated:
- bug80259/testmodule.qdocconf; dropped fileextensions
- illformatted_documentation/illformatted_documentation.qdocconf;
dropped warninglimit.
The following configuration files included `testcpp.qdocconf` and as
such transitively receives the content from `config.qdocconf`. This
dependency will be dropped in a follow-up patch.
- config/docbook_testcpp.qdocconf
- config/docbookext_testcpp.qdocconf
- config/ignoresince.qdocconf
- config/nestedmacro.qdocconf
- config/properties.qdocconf
- config/scopedenum.qdocconf
- config/testcpp_singleexec.qdocconf
- config/testqml.qdocconf
- config/testtemplate.qdocconf
- config/webxml_testcpp.qdocconf
Finally, `examples_qhp.qdocconf` includes `testqml.qdocconf`, which
includes `testcpp.qdocconf`, and thus transitively receives the content
previously contained in `config.qdocconf`. This dependency chain will be
broken in a follow-up patch.
Task-number: QTBUG-119500
Change-Id: I7005c5931c44f653e25af08203685d1a3ce614e0
Reviewed-by: Topi Reiniö <topi.reinio@qt.io>
Remove `docbookext.qdocconf` from the shared configuration for
`tst_generatedOutput`. Replicate its contents directly in the various
configuration files that previously included it. Although this causes
some duplication, it's a step in the direction of making the test
projects entirely self-contained.
Task-number: QTBUG-119500
Change-Id: I42d70e19226008d261eca7e83e4ec4f65f106919
Reviewed-by: Topi Reiniö <topi.reinio@qt.io>
Remove `webxml.qdocconf` from the shared configuration for
`tst_generatedOutput`. Replicate its contents directly in the various
configuration files that previously included it. Although this causes
some duplication, it's a step in the direction of making the test
projects entirely self-contained.
Task-number: QTBUG-119500
Change-Id: I67fbb69184950a9a2ee264409297380cd102f3a8
Reviewed-by: Topi Reiniö <topi.reinio@qt.io>
This change moves the `line_comments` test project from
tst_generatedOutput to the test data for tst_validateQdocOutputFiles.
Task-number: QTBUG-119500
Change-Id: Ibf4ccf8fd37a10d79987280db36855aa78ea5700
Reviewed-by: Topi Reiniö <topi.reinio@qt.io>
Since 926959d2fe, most tests for QDoc
reside in `src/qdoc/qdoc/tests`. This directory is included by the
build system if `QT_BUILD_TESTS` is set. Tests in this directory are
included by its `CMakeLists.txt` file. However, Qt's CI system, COIN,
sets the variable `QT_BUILD_STANDALONE_TESTS`. This variable is checked
in `tests/auto/qdoc/CMakeLists.txt`, and the tests for QDoc are
included if the condition is satisfied. This means that when adding new
tests for QDoc, two `CMakeLists.txt` files must be modified for
essentially the same purpose.
This change modifies `tests/auto/qdoc/CMakeLists.txt` such that the
list of tests can be maintained in one location.
Task-number: QTBUG-119500
Change-Id: I437b9cf7823e33fc4a4e0cd205aa4a8bad5dc674
Reviewed-by: Qt CI Bot <qt_ci_bot@qt-project.org>
Reviewed-by: Topi Reiniö <topi.reinio@qt.io>
A test called tst_generatedOutput already exists for testing QDoc's
generated files. That test suffers from multiple shortcomings, such as
hand-rolled comparison, a joint expected output directory for all
tests, and explicit listing of expected files, to name a few. These
properties of tst_generatedOutput make it cumbersome to maintain and
extend that test.
As the material form of the output test is changing, comparing test
results against tst_generatedOutput as reference may be misleading for
the sake of proper test statistics. Therefore, this patch introduces a
new test for QDoc, tst_validateQdocOutputFiles. It runs QDoc in order
to generate documentation for projects contained in its `testdata`
subdirectory. The test is data driven, populated by the QDoc projects
(identified by .qdocconf files) found in the subdirectories of
`testdata`. The implementation is partially taken from
tst_generatedOutput.
The intention is to let this new test replace tst_generatedOutput as
soon as coverage parity is achieved.
This patch includes:
- The test itself.
- A `testdata` directory that contains a simple test that replicates
the minimum QDoc configuration according to the QDoc manual, and its
expected output. This project serves two purposes: it validates that
the test works as intended, and it keeps the QFETCH macro from
asserting over missing testdata.
- Necessary updates to build system files.
- A `README.md` for the test that describes its intended purpose and
how to extend it.
Task-number: QTBUG-119500
Change-Id: I8e8295d2040fa039d66d36861138889ef32d30af
Reviewed-by: Topi Reiniö <topi.reinio@qt.io>
The QDoc manual contains incorrect syntax for the use of QDoc's
`extraimages` configuration variable. This change corrects the mistake.
As "drive-by" change, the surrounding text is modified to make it
clearer.
Inspecting the documentation for the `stylesheets` and `scripts`
configuration variables (they're mentioned in the bug report) exposed
another oddity in the manual, which is also addressed herein.
Pick-to: 6.7 6.6 6.5
Fixes: QTBUG-121226
Change-Id: I94e37b29de20dc932a2de532d6e5a4f4a7d36512
Reviewed-by: Topi Reiniö <topi.reinio@qt.io>
QDoc documentation projects must define an `outputdir` that specifies
the directory into which QDoc will create files for the project. This
variable can be defined in the project's .qdocconf file, or with the
`-outputdir` command line option.
QDoc can generate output in various formats, specified by the
`outputformats` configuration directive. Each output format can specify
a directory into which QDoc shall place the files created for that
format through the `outputsubdir` configuration variable.
If the configuration for a project specifies the `nosubdirs` variable
for any of the configured output formats, QDoc drops the last directory
in the path hierarchy of the output directory (specified with the
`outputdir` configuration variable or passed via `-outputdir` on the
command line) for that format. Thus, given the following configuration:
outputdir = /tmp/foo
outputformats = HTML DocBook
HTML.outputsubdir = html
HTML.nosubdirs = true
DocBook.outputsubdir = docbook
DocBook.nosubdirs = true
Instead of placing output in `/tmp/foo/html` and `/tmp/foo/docbook`,
QDoc will place its output into `/tmp/html` and `/tmp/docbook`.
`/tmp/foo` will neither be created nor (if pre-existing) modified.
If `nosubdirs` is set and the `outputsubdir` variable isn't specified
for the given format, QDoc defaults to the name `html`.
This change modifies QDoc's behavior such that, when both `nosubdirs`
and `outputsubdir` are set, the last directory in the `outputdir`
hierarchy isn't removed before appending `outputsubdir`. This ensures
that the path specified by `outputdir` will be the top level directory
unless the `outputsubdir` explicitly navigates out of that hierarchy
with a relative path.
[ChangeLog][QDoc][Behavior Change] The `nosubdirs` configuration
variable no longer removes the last segment in the `outputdir` path.
To retain previous behavior for projects that define `outputsubdir`
and `nosubdirs`, prepend `outputsubdir` with `../`.
Task-number: QTBUG-77650
Task-number: QTBUG-119500
Change-Id: I310b86db3689d6236cd6dc213b1dbd28906f6531
Reviewed-by: Topi Reiniö <topi.reinio@qt.io>
test.qdocconf is shared by four tests. Remove the dependency to
config.qdocconf by replicating the contents in test.qdocconf. This
may reduce the need for future decoupling and ease work related to
decoupling the tests further.
Task-number: QTBUG-119500
Change-Id: I8329add639be0c74334da19e40cfcfc6c7671cb0
Reviewed-by: Topi Reiniö <topi.reinio@qt.io>
Move the macro definition to the one project that uses it, instead of
keeping it for all test projects.
Task-number: QTBUG-119500
Change-Id: I87d3d5f4e4877e9ddfa6b3d751a275c98edf2a21
Reviewed-by: Topi Reiniö <topi.reinio@qt.io>
The `expected_output` directory for QDoc's generated output test
contains files that aren't generated by the test and thus not
expected. Remove them.
Change-Id: Ic3752a9f0c4edc1a68aa95232120a8a2b7a3e0ae
Reviewed-by: Topi Reiniö <topi.reinio@qt.io>
This patch introduces a new block command, `\compareswith` and
`\endcompareswith`, to QDoc.
The `\compareswith` command takes two arguments: a comparison category
and a space-delimited list of types for which the comparison category
applies. The comparison category argument must be one of the following:
`strong`
`weak`
`partial`
`equality`
The comparison category statement is generated as part of class
documentation, immediately preceding the admonition about thread
safety, and outputs e.g:
`This class is equality-comparable with Foo, Bar, and Baz.`
Any text that follows the `\compareswith` command prior to the closing
`\endcomparewith` command is generated immediately following the
comparison category statement.
This patch makes the following changes to QDoc:
- The command is added to the command hierarchy in `DocParser`,
as is code for processing the command.
- `DocPrivate` is modified to keep a map of comparison categories, a
list of types, and the detailed description.
- `Doc` is modified such that the above map can be retrieved.
- A new method is added to the `Generator` base class for generators.
The `HTMLGenerator` and `DocBookGenerator` subclasses are modified
to generate the comparison category listing for comparable types.
- Documentation of the new command is added to the QDoc manual.
- The `generatedOutput` test documentation project for the related
\compares command is extended to exercise the new command.
- Two new atom types, `ComparesLeft`, `ComparesRight`, are introduced.
- `Text` sees the addition of a new private constructor,
`Text(Atom*, Atom*)`, as well as the public method
`splitAtFirst(Atom::AtomType)`.
- The generated output test for QDoc is extended to exercise the new
block command in various ways.
In passing, ensure that DocParser::getRestOfLine() (which the
\compareswith command uses) correctly removes trailing backslashes
from a multi-line argument string.
Fixes: QTBUG-117913
Task-number: QTBUG-104110
Task-number: QTBUG-119610
Change-Id: Ie0c78443d2cc8b159594e725102eec5fab2f7598
Reviewed-by: Luca Di Sera <luca.disera@qt.io>
This patch introduces a new command, `\compares`, to QDoc.
The command takes an argument that indicates the comparison category of
the entity being documented. The argument must be one of the following:
`strong`
`weak`
`partial`
`equality`
The comparison category statement is generated as part of class
documentation, immediately preceding the admonition about thread
safety, and outputs e.g:
`This class is equality-comparable.`
This patch makes the following changes to QDoc:
- The new header file, `comparisoncategory.h`, contains a new enum,
`ComparisonCategory`, and helper functions to convert between
a string representation and a `ComparisonCategory` enum value.
- A related implementation file containing the documentation for the
contents in the header.
- The command is added to the command hierarchy in `CppCodeParser`,
as is code for processing the command.
- `Node` is modified such that a `Node` contains a member that keeps
track of its own comparison category (one of `Strong`, `Weak`,
`Partial`, `Equality`, or `None`).
- `QDocIndexFiles` is modified such that the comparison category is
recorded in the .index-file and also read back in from said file(s).
- A new method, `generateComparisonCategory`, is added to the
`Generator` base class for generators. The `HTMLGenerator` and
`DocBookGenerator` subclasses are modified to generate the comparison
category.
- Documentation of the new command is added to the QDoc manual.
- The `generatedOutput` test sees the addition of a new test
documentation project that exercises the new command.
Fixes: QTBUG-117912
Task-number: QTBUG-104110
Change-Id: Ibe7cf6f165b9cf1fdd6e1cbf5fbea8686fdf2e47
Reviewed-by: Edward Welbourne <edward.welbourne@qt.io>
Reviewed-by: Luca Di Sera <luca.disera@qt.io>
Reviewed-by: Topi Reiniö <topi.reinio@qt.io>
Recent changes to QDoc from Qt 6.7 onwards require libclang 15 or
newer. This patch updates configure.cmake such that the build target
for QDoc is made available only if the available libclang satisfies
the version criteria. It also modifies QDoc's documentation.
[ChangeLog][QDoc] QDoc now requires LLVM 15 or newer.
Task-number: QTBUG-111580
Fixes: QTBUG-119502
Change-Id: I4a0526f7b3f6c330996be0170ffa76c292e6e2df
Reviewed-by: Alexandru Croitor <alexandru.croitor@qt.io>
Since a refactoring (d7eeb6b0f7), QDoc no
longer parses trailing backslashes immediately preceding a newline
character as line continuation character correctly, in that content in
the continued line is duplicated. This is due to the refactoring not
properly updating the position.
The refactoring caused another side effect, addressed in
d988115e06. That change caused a new side
effect that may cause leading and trailing whitespace characters in a
continued line to end up verbatim in the continued line.
This change seeks to address these two problems in the following way:
- Ensure the main loop of the method updates the starting position
for the line of text at the end of each iteration.
- If a trailing backslash has been encountered, return a simplified
string. This ensures that sequences of internal whitespace is
replaced by a single space character.
- Change a local variable name to better reflect what it represents.
- Update the documentation for the method to account for the behavior
change.
The reintroduction of `simplified()` return values may possibly have
unintentional consequences. For example, it may impact parsing of
regular expressions, as seen as side-effect of the original
refactoring.
Fixes: QTBUG-118558
Pick-to: 6.6
Change-Id: I5bbf51b1923a5e04f324c3f92aeb1cceff8aab7c
Reviewed-by: Topi Reiniö <topi.reinio@qt.io>
When generating documentation for a module that is in a state, for
example, "Technological Preview", as defined by QDoc's `\modulestate`
command, classes that belong to that module are supposed to feature
an entry in their requisites table (along with header, CMake/qmake
lines, etc).
If the documentation for such a class contains a QDoc command that
triggers the creation of `DocPrivateExtra`, such as any `\section`
command, the entry in the requisites table disappears. This is due to
the fact that `Generator::formatExtra()` categorically returns the
status that's recorded in the `metaTagMap` of the `DocPrivateExtra`, if
one exists, even if it's empty. As such, when e.g. a `\section` command
is encountered, an (empty) such `metaTagMap` comes into existence for
that documentation block.
This patch contains a minimal QDoc project that reproduces the
misbehavior, and that serves to confirm that the bugfix contained
herein solves the observed issue.
The behavior correction ensures that `Generator::formatExtra` checks
that the status obtained from `DocPrivateExtra::metaTagMap` isn't
empty. If it is, allow processing the other possibilities. Else, return
early.
Pick-to: 6.6
Fixes: QTBUG-117778
Change-Id: I47525f69e31d0a924ca9ab380c6c7255040eca6c
Reviewed-by: Kai Köhne <kai.koehne@qt.io>
Reviewed-by: Topi Reiniö <topi.reinio@qt.io>
In the late 2000s, Java bindings for Qt were released as the project
"qt-jambi". This was discontinued at the end of that decade and spun
off as an open source project, QtJambi, currently maintained by Omix
Visualization (https://github.com/OmixVisualization/qtjambi).
When generating HTML output, QDoc replaces certain characters that are
reserved in HMTL with their HTML entity counterparts. This is done in
the `HtmlGenerator::protect()` method. However, the method also contains
a special case that replaces certain characters that /aren't/ reserved
in HTML, with their HEX counterparts without leading `0`. The sparse
documentation for this special case suggests it is there to satisfy the
Javadoc generator.
The special case is intended to apply to the sequence `*/`, and to a
full stop (`.`) if two full stops occur with any one character between
them. Going by the code comment, the intention of the latter is to
escape the last full stop in the abbreviations of the latin expressions
`id est` (`i.e.`) and `exempli gratia` (`e.g.`).
The implementation is rather naive; for the `*/` sequence, the check
is buggy (off-by-one error in the check for the characters `*` and `/`).
For the spaced dot pair, the implementation fails to take into account
its impact on e.g. ellipses or `6.6.6`.
The existence of this special case for the Javadoc generator may suggest
that QDoc featured a Javadoc generator in the past, which is something
it certainly doesn't feature now. It may also suggest that output from
QDoc was used as input to Javadoc in some form or another. Since QDoc
with Qt 5.15, QDoc features a generator for DocBook, which is more
suitable for use as input to some other generation tool than HTML is.
This patch removes the special case branch. This may cause QDoc to
generate `.` instead of `.` in its HTML output in multiple
locations. This is to be expected.
Pick-to: 6.6 6.5
Change-Id: I45734c11ad5891016dd19b211d54f218c2def3a1
Reviewed-by: Luca Di Sera <luca.disera@qt.io>
Reviewed-by: Topi Reiniö <topi.reinio@qt.io>
The configuration variable wasn't actually handled by QDoc and was
therefore removed in f73225d252.
This patch removes remaining references in the QDoc manual that were
left behind by mistake.
Change-Id: I2f37314021c182d7ec92cc28bc630e342c333567
Reviewed-by: Luca Di Sera <luca.disera@qt.io>
Reviewed-by: Topi Reiniö <topi.reinio@qt.io>
- Flatten the method by inverting two conditional checks. This allows
for dedenting the bulk of the method.
- Replace lengthy "or" condition with a QStringList and use of it's
.contains() method.
- const qualify local variable that doesn't mutate.
Task-number: QTBUG-117470
Pick-to: 6.6 6.5
Change-Id: I80d64111bf4a62f0eb2bb6aa4d8ae4cd13d3e28a
Reviewed-by: Luca Di Sera <luca.disera@qt.io>
Reviewed-by: Topi Reiniö <topi.reinio@qt.io>
Paul Wicking