| Commit message (Collapse) | Author | Age | Files | Lines |
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
| |
The .index files were missing an attribute for C++ properties that
are read-only.
For a PropertyNode, if setWritable() was not explicitly called,
the read-only status was based on whether the property's access
functions included a getter method. When reading nodes from an index,
these access functions are not restored when constructing a
PropertyNode as that information is not needed anymore. A side-effect
of this was that all C++ property nodes read from index were
considered read-only.
QDoc also supports resolving the read-only status for a QML property
based on the associated C++ property of a class that the parent QML
type instantiates. If this instantiated class was read from index,
that meant that the read-only status was resolved incorrectly.
To fix, add writable="false" attribute for all read-only C++ properties
written to index, and explicitly call setWritable() when reading them
back in.
Pick-to: 6.5
Fixes: QTBUG-113015
Change-Id: Iaf8276a892d9a764fed9a67ebd005481c16bba17
Reviewed-by: Paul Wicking <paul.wicking@qt.io>
|
|
|
|
|
| |
Change-Id: I0037d36902edc7de8689aa1a11e1e11b0ac85e88
Reviewed-by: Thiago Macieira <thiago.macieira@intel.com>
|
|
|
|
|
|
|
| |
Use the variant with compile-time type checking.
Change-Id: Ib7da65963af8ff11a39d52ab447ebd91c5ec7404
Reviewed-by: Thiago Macieira <thiago.macieira@intel.com>
|
|
|
|
|
|
|
|
|
|
|
| |
Replace most uses of QLatin1String by _L1, QStringLiteral by _s.
Use tr() for user-visible strings. Reorganize the loop inside
QDBusViewer::dumpMessage() slightly to make it less sensitive to
translation changes.
Change-Id: Id987bd0efe06d0efd80c57982c3c2a6a031c369a
Reviewed-by: Thiago Macieira <thiago.macieira@intel.com>
|
|
|
|
|
|
|
|
|
|
|
|
|
|
| |
This replaces connections to deprecated signal
QDBusConnectionInterface::serviceOwnerChanged() and avoids a warning
being printed at run time.
QDBusServiceWatcher emits the serviceOwnerChanged() signal
when services are registered and unregistered, so this one
signal replaces 3 signals from QDBusConnectionInterface.
Fixes: QTBUG-28618
Change-Id: Ic2afa25e8c6438ead93c75b4c8864e557ba70714
Reviewed-by: Thiago Macieira <thiago.macieira@intel.com>
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
| |
Following recent bug fixes in QDoc, it has become apparent that the
implementations of `Utilities::canonicalizeFileName` and
`Doc::canonicalTitle` are mostly identical. This violates the DRY
principle. The use of the former method to normalize generate values for
HTML class attributes, shows that the problem the method solves is also
closely related to generating HTML. The latter method specifically
generates "URL friendly" strings for fragment identifiers in URLs. This
indicates that both methods are poorly named, and that they both see use
relating to the same problem domain.
This patch merges the two implementations to reduce code duplication.
`Doc::canonicalTitle` is removed, and `Utilities::canonicalizeFileName`
is renamed to `asAsciiPrintable` to better represent its purpose. The
documentation is updated. All call sites are updated to use the new
method. As there is no unit test for either method, no tests are
modified.
Fixes: QTBUG-113606
Change-Id: I1fd6a654075fdf8e719bf504b1d702737dd1e42e
Reviewed-by: Topi Reiniö <topi.reinio@qt.io>
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
| |
When generating files, QDoc normalizes the string that's used for the
file's name. This normalization is done by
`Utilities::canonicalizeFileName`. The method returns a string stripped
for non-alphanumeric characters, with space replaced by hyphens, and
any repeating or trailing hyphens removed.
This causes the removal of non-ascii-printable characters, such as
a range of latin characters (e.g. 'ß`, 'ø', etc), and any non-latin
script (Arabic, Chinese, etc). If the file name, for example defined by
the `\page` command, contains nothing but disallowed characters, the
file simply isn't generated. However, QDoc doesn't warn the user in this
case.
This patch extends QDoc's generated output test to reproduce this issue.
The test serves as proof of the misbehavior and as regression discovery
mechanism.
The patch modifies `Utilities::canonicalizeFileName` such that it
appends a hash to "canonical" titles that contain characters not
considered legal in file names. For the purpose of compatibility across
file systems, legal characters are considered lowercase a-z, the digits
0-9, and the hyphen character. Other symbols and characters are still
removed. However, when encountering characters that are not part of a
subset of ascii-printable characters (ascii decimal 32-126, inclusive),
QDoc now appends a hash of the original file name string to the string
it returns as "canonicalized".
[ChangeLog][QDoc] QDoc now appends a hash of the original file name to
the file name(s) of files where the name contains non-ascii characters.
This means QDoc now generates files for pages with names written in
non-latin characters.
Fixes: QTBUG-113585
Change-Id: Icb0f8a094ed8eea38fb3ac954af318bb78f3a755
Reviewed-by: Topi Reiniö <topi.reinio@qt.io>
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
| |
QDoc employs a support library, "catch_generators", to
provide custom support for the data-generation that certain tests use or
might want to use when using the Catch2 testing framework, which QDoc
uses for some of its tests.
"catch_generators" was currently kept under "tests/auto/qdoc" and its
headers were included and used directly by related tests by relative
paths.
Due to a certain restructuring that is happening in QDoc, with one of
the goals, among others, being to increase the locality of QDoc-related
code under "src/qdoc", the "catch_generators" support library is now
moved under "src/qdoc".
To allow code that depended on it to keep their usages without requiring
the addition of some relative paths from the "tests" directory to the
"src" directory, a library target, "Qt::QDocCatchGeneratorsPrivate" was
created for it.
The target can be linked-to to gain access to the
previously-directly-used headers, with include path
"catch_generators/.*".
To allow for this specific include path to work, the internal directory
structure for "catch_generators" was slightly modified with the
addition of some intermediate directories in between its root and the
library headers.
The root "CMakeLists.txt" file for the QDoc project was modified to add
the moved "catch_generators" as a subdirectory, to include it in the
build process.
"catch_generators" contains its own test code under the subdirectory
"tests".
Previously the test target in "tests" included the relevant headers from
the library by use of relative paths to its sources.
Now that the library is exported as a target, the "CMakeLists.txt" file
under "tests" was modified to rely on linking to the library itself to
obtain access to the required headers.
Similarly, targets under "tests/auto/qdoc" that used the dependency now
link to it instead. Hence, their "CMakeLists.txt" files were modified to
avoid using the dependency as an include directory and instead use
"Qt::QDocCatcGeneratorsPrivate" as a library.
The inclusions of the "catch_generators" headers in
relevant sources was modified to respect the new "catch_generators/.*"
path.
Additionally, "catch_generators" exposed a top level header,
"qdoc_catch_generators.h", including certain headers in the library that
were expected to be commonly used by tests, so that the consumers did
not have to include multiple headers when using various common generators.
The header was removed in favor of including the library headers
themselves now that they have a well-defined root provided by the
exposed target.
Sources that included the header were modified to include only their
relevant headers from "catch_generators", respecting the additional
granularity.
Due to the Qt Project CI performing discovery of tests by configuring
only the "tests" directory of the module; the moved "catch_generators",
which contained its own testing code, will now escape the automated
testing in CI for its own tests, as the relevant target does not reside
under the "tests" directory of the repository.
To avoid this issue, the "CMakeLists.txt" file under "tests/auto/qdoc",
was modified to `include` the "CMakeLists.txt" file that describes
"catch_generators"' test target, so as to "mirror" the test under the
"tests" directory.
To support working when included, the "CMakeLists.txt" file that
describes "catch_generators"' test target was modified to refer to any
relevant relative path by prefixing the value of
`CMAKE_CURRENT_LIST_DIR`, so that the relative paths would not be
incorrectly resolved when using `include`.
Due to this "mirroring", the relevant test target would be configured
twice when the whole repository was configured, resulting in an error.
To ensure that this is not the case, the `include` directive was hidden
behind `QT_BUILD_STANADALONE_TESTS`, which is not set during a general
configuration of the repository but is set when CI performs
test-discovery on the "tests" directory.
Similarly, the "tests" directory of a repository is configured only when
`QT_BUILD_TESTS` is `ON`, which further ensures that the required
dependencies, such as `Qt::Test`, will be found before the directory is
configured.
By having moved the test declaration outside of the `tests` directory,
the test will always be configured, failing to find its dependencies
when this happens.
To avoid the issue, the `add_subdirectory(tests)` directive in
`src/qdoc/catch_generators/CMakeLists.txt` was conditioned over `QT_BUILD_TESTS`.
Certain files that were missing an license header were enhanced with it,
as the lack of an header will now be an issue outside the "tests" directory.
Change-Id: I0bca477b7da75c121c24b8528fc9defa26a6123e
Reviewed-by: Topi Reiniö <topi.reinio@qt.io>
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
| |
When generating fragment identifiers from a title, QDoc normalizes the
string that's used as fragment identifier. This normalization is done by
`Doc::canonicalTitle()`. This method returns a string that is stripped
from non-alphanumeric characters, has space(s) replaced by one hyphen,
and any repeating or trailing hyphens removed.
This causes the removal of certain characters, such as 'ß', '大', etc.
For documentation written in languages that contain mostly non-latin1
characters, such as Chinese, this means fragment identifiers may be
empty, such that links to these anchors (e.g. from a table of contents)
lead to nowhere.
This patch adds test data to QDoc's generated output test to reproduce
the issue. The Chinese test data is courtesy of the bug reporter. The
test data also contains other characters from Latin scripts, as during
investigation of a solution to the bug, these appeared as separate
triggers of the misbehavior. The modified test also serves to catch
possible future regressions.
The patch modifies `Doc::canonicalTitle` such that it appends a hash to
"canonical" titles that contain characters that are not considered legal
entities in a canonical title. In this context, legal characters are
lowercase a-z, digits 0-9, and the dash (`-`). Other symbols and
characters are removed. When encountering any character that is either a
non-printable ascii character or ascii character outside a subset (ascii
decimal 32-126, inclusive), QDoc will append a hash of the original
string to the fragment identifier it generates. This means that the
canonical title for a string that contains, for example, a mix of
allowed and disallowed characters, will consist of the allowed
characters and a hash of the original string appended to the final
string.
The patch changes the loop in `canonicalTitle` to a ranged for loop over
a const-ref, and adds precision to a code comment (precision based on
timing the execution of the two implementations of this method one
million times).
Finally, the patch adds documentation for `Doc::canonicalTitle`, as that
didn't exist previously.
[ChangeLog][QDoc] QDoc now appends a hash of the original title to the
fragment identifier generated for that title if the title contains
non-ascii characters. This means QDoc now generates fragment identifiers
for titles that are written in non-latin characters.
Fixes: QTBUG-64506
Change-Id: Idc62677b9950becea662d8ff5ead1f631ec26bc3
Reviewed-by: Topi Reiniö <topi.reinio@qt.io>
|
|
|
|
|
|
|
|
|
|
|
| |
The addendum added to the C++ and QML methods, properties,
and signals, lack the necessary styling. They are added as
a simple HTML para, without the appropriate admonition CSS
class, which is normally used for a \note.
Pick-to: 6.5
Change-Id: I10cb9d51c587fb21024168a57e8661f7da0ad323
Reviewed-by: Topi Reiniö <topi.reinio@qt.io>
|
|
|
|
|
| |
Change-Id: I452eb27d2c86ff1302b53474f9be884175c70ab5
Reviewed-by: Venugopal Shivashankar <Venugopal.Shivashankar@qt.io>
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
| |
QDoc employs a very small support library, "catch_conversions", to
provide better output for certain types when used with the Catch2
testing framework, which QDoc uses for some of its tests.
"catch_conversions" was currently kept under "tests/auto/qdoc" and its
headers were included and used directly by its sibling tests by relative
paths.
Due to a certain restructuring that is happening in QDoc, with one of
the goals, among others, being to increase the locality of QDoc-related
code under "src/qdoc", the "catch_conversions" support library is now
moved under "src/qdoc".
To allow code that depended on it to keep their usages without requiring
the addition of some relative paths from the "tests" directory to the
"src" directory, a library target, "Qt::QDocCatchConversionsPrivate" was
created for the support library.
The target can be linked-to to gain access to the
previously-directly-used headers, with include path
"catch_conversions/.*".
To allow for this specific include path to work, the internal directory
structure for "catch_conversions" was slightly modified with the
addition of some intermediate directories in between its root and the
library headers.
Targets under "tests/auto/qdoc" that used the dependency now link to it
instead. Hence, their "CMakeLists.txt" files were modified to avoid
using the dependency as an include directory and instead use
"Qt::QDocCatchConversionsPrivate" as a library.
The inclusions of the of the "catch_conversions" headers in
relevant sources was modified to respect the new "catch_conversions/.*"
path.
The root "CMakeLists.txt" file under "src/qdoc" was modified to add the
relevant library as a subdirectory.
Change-Id: Iec24ca3877a48a42a55ff406309813aa083ab23f
Reviewed-by: Paul Wicking <paul.wicking@qt.io>
Reviewed-by: Qt CI Bot <qt_ci_bot@qt-project.org>
Reviewed-by: Topi Reiniö <topi.reinio@qt.io>
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
| |
QDoc uses the Catch2 testing-framework for some of its tests.
The dependency is included as a header-only library that lived under
"tests/auto/qdoc/".
Due to a certain restructuring that is happening in QDoc, with one of the
goals, among others, being to increase the locality of QDoc-related code
under "src/qdoc", the Catch2 dependency is now moved under "src/qdoc".
To allow tests that depend on it to keep their usages without requiring
relative paths from the "tests" directory to the "src" directory, a
library target, "Qt::QDocCatchPrivate" was created for the dependency.
The target can be linked to to have access to the Catch2 dependency and
the Catch2 header can be included with "catch/catch.hpp".
To allow for this specific include path to work, the internal directory
structure of the Catch2 dependency was slightly modified, adding some
additional intermediate directories in between its root and the library
header.
Tests under "tests/auto/qdoc" that used the dependency now link to it
instead. Hence, their "CMakeLists.txt" files were modified to avoid
using the dependency as an include directory and instead use
"Qt::QDocCatchPrivate" as a library.
The relevant inclusion of the Catch2 header in those sources was
modified to respect the new "catch/catch.hpp" path.
Change-Id: Ifd462f582d197f78a8ffbbbe7b2cf9ae25dbc991
Reviewed-by: Paul Wicking <paul.wicking@qt.io>
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
| |
QDoc's \brief command takes an entire paragraph as its argument, and
allows for the processing QDoc commands or macros that appear in the
argument. Due to QDoc's internals, such commands may consume newline
characters that the \brief command relies upon as its end condition.
Thus the \brief command may erroneously include the following content
as part of its argument.
A previous patch addressed this issue specifically for `CMD_KEYWORD`.
However, there are still multiple possible pathways in QDoc's code
where the bug may be triggered. This patch seeks to add guards against
this (mis)behavior in the following ways:
Modify the `scopedenum` output test by adding a `\brief` to it, as that
already makes use of `CMD_SINCELIST`. This modification exposes that
the bug is also triggered in this case. To guard against the behavior,
add a call to `leavePara()` in the parsing of `CMD_SINCELIST`. This
resolves the issue, with no visual impact when generating the
documentation for Qt.
In parsing `CMD_IMAGE`, there's a call to `getRestOfLine()` when
parsing the alternate text for an image. This patch adds test data for
a page that features an image with an alternate text right at the top.
This doesn't trigger the bug. The test data is kept as part of this
patch as proof that the bug does not occur in this case, and to guard
against possible future regressions.
In parsing `CMD_OMITVALUE`, there's a call to getRestOfLine() while
skipping potential description paragraphs. Modify the `scopedenum`
test by adding a `\brief` to the `TestQDoc::Test::ScopedEnum` enum
documentation, and rearrange the valuelist such that an `\omitvalue`
command immediately follows the `\brief`. This triggers the bug. Add a
call to `leavePara()` upon entering the case. This resolves the issue,
with no visual impact when generating the documentation for Qt.
In parsing of QDoc's line comments, `//!`, there's a call to
`getRestOfLine()` while also adjusting the position. While adding a
call to `leavePara()` in the parsing of line comments modifies the
output of QDoc in what is arguably a correct way (that is, paragraphs
are inserted where new paragraphs should be reasonably expected), that
modification causes an unwanted side-effect in `CMD_BRIEF`:
the consumption of the newline character by `getRestIfLine()` breaks
`CMD_BRIEF` if one inserts a line comment within the arguments to the
command and continue the argument on the following line. For example:
\brief SANTA //! wait for it...
MOZZARELLA!
will, surprisingly, make the brief contain only SANTA, not SANTA
MOZZARELLA! as one would expect.
As the proposed workaround of inserting calls to `leavePara()` is found
to have unwanted side-effects on `CMD_BRIEF` in the case of QDoc line
comments, resolving this is left for a future change.
Task-number: QTBUG-113118
Change-Id: Ic71e7e15c62a9beb834690f24f7538500346cb60
Reviewed-by: Topi Reiniö <topi.reinio@qt.io>
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
| |
The new guidelines for examples in Qt recommend one avoids use of
the word "Example" in an example's name. The QDoc manual contains
documentation for the example manifest files generated by QDoc.
This documentation references content generated with a naming
scheme that doesn't adhere to the new guidelines. This patch
removes the use of the word 'example' from example names such that
example content in the QDoc manual reflects the new example naming
scheme in Qt.
Fixes: QTBUG-113393
Change-Id: Idd95bd06c6b67471aed5cb6147386235ceac79c7
Reviewed-by: Topi Reiniö <topi.reinio@qt.io>
|
|
|
|
|
|
| |
Pick-to: 6.5
Change-Id: Ie2cf46d7032f7a019d1a6e386d868e7ab0d413a8
Reviewed-by: Jarek Kobus <jaroslaw.kobus@qt.io>
|
|
|
|
|
|
| |
Pick-to: 6.5
Change-Id: I638ae91b98601682ed0dca2eaf4855c1e11577f4
Reviewed-by: Jarek Kobus <jaroslaw.kobus@qt.io>
|
|
|
|
|
|
| |
Pick-to: 6.5
Change-Id: I9407555b550b9e2e74d9c2f19286077d780ed41d
Reviewed-by: Jarek Kobus <jaroslaw.kobus@qt.io>
|
|
|
|
|
|
|
|
| |
In some cases, remove QString::number() for int.
Pick-to: 6.5
Change-Id: I60260afbbb3045448025983e37974667f2eeb51a
Reviewed-by: Jarek Kobus <jaroslaw.kobus@qt.io>
|
|
|
|
|
|
| |
Pick-to: 6.5
Change-Id: I422dc9df9dfcbafbdde99708692e4b59d112e99e
Reviewed-by: Jarek Kobus <jaroslaw.kobus@qt.io>
|
|
|
|
|
|
|
|
|
| |
Break out of the while on EOF when reading comments.
Pick-to: 6.5
Fixes: PYSIDE-2311
Change-Id: I2047220950f9d9b424d04c1e34e32eeb5a5b83fa
Reviewed-by: Joerg Bornemann <joerg.bornemann@qt.io>
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
| |
Recent refactoring of `DocParser::insertTarget` exposed that the method
is responsible for the handling of two separate concepts in QDoc, the
commands `\target` and `\keyword`, respectively. Handling of the latter
command was added to the method in question by extending it's signature
with a boolean parameter, whose value was significant in deciding which
code path to follow. However, this API design is no longer considered
appropriate for QDoc, as discussed in review of the previous
refactoring.
This patch extracts the code responsible for inserting keywords into
their related data structure from `DocParser::insertTarget`, and adds
this code to a new member method, `DocParser::insertKeyword`. The
signature of the former method is updated and the relevant call sites
are updated to call the correct method.
The new method is documented as part of its introduction to the code
base. Given that the two methods have striking similarities,
documentation is added to `DocParser::insertTarget` in its new form.
Fixes: QTBUG-113126
Change-Id: Id29bc655c15b6e12726100eb1f33adbf97487236
Reviewed-by: Topi Reiniö <topi.reinio@qt.io>
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
| |
A recent refactoring extracted a method from `DocParser::insertTarget`
that allows and early return. This makes the else branch redundant, as
control will always exit the method if the `if` condition is satisfied.
This allows for flattening the method further.
This change thus flattens the method by removing the else statement and
flattening the code in that branch. The remaining code features another
if/else check. This change adds a return statement to the if statement,
allowing the removal of the following else statement and the flattening
of that branch, too.
Task-number: QTBUG-113126
Change-Id: If0e7436f8bb98924dd54c9d9f04a8a7a4d7566a9
Reviewed-by: Topi Reiniö <topi.reinio@qt.io>
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
| |
`DocParser::insertTarget` has a conditional check at the start of the
method, that, if satisfied, causes QDoc to generate a warning. The rest
of the method is contained in the else block that follows.
This patch extracts a method, `DocParser::warnAboutPreexistingTarget`,
that is responsible for issuing that warning, and modifies
`DocParser::insertTarget` to return early if the condition is
satisfied. This allows further refactoring of the latter method.
The new method is fully documented. As this new method impacts the
documentation for QDoc warnings, that is also modified in this patch.
Task-number: QTBUG-113126
Change-Id: Iba54e67862555fba71ec774261e0e0fbea638238
Reviewed-by: Topi Reiniö <topi.reinio@qt.io>
|
|
|
|
|
|
|
|
|
| |
A recent change removed the \alias command from QDoc,
and failed to remove a link to it from the QDoc warnings
documentation. This patch remedies that mistake.
Change-Id: Ia2ef4d095fc548e754312317b4b07f006ccc5a59
Reviewed-by: Topi Reiniö <topi.reinio@qt.io>
|
|
|
|
|
|
|
|
|
|
| |
This patch is a port of b7849d42efff91a4d247a4028d6c129f3742743a
for DocBook.
Pick-to: 6.5
Change-Id: I0220691da3e0827bc89e05912bcbb723d8490cf5
Reviewed-by: Paul Wicking <paul.wicking@qt.io>
Reviewed-by: Topi Reiniö <topi.reinio@qt.io>
|
|
|
|
|
|
|
|
|
|
|
|
| |
Previously, this parameter could only be set from the command line.
Now, it can also be set from a qdocconf file, like almost all other
parameters. There was never a reason why it was read only from the
command line.
Pick-to: 6.5
Change-Id: Ib2877e8f4ef6155ac9434e982331de826d7df18c
Reviewed-by: Paul Wicking <paul.wicking@qt.io>
Reviewed-by: Topi Reiniö <topi.reinio@qt.io>
|
|
|
|
|
|
|
|
|
| |
The DocBook generator was the only one using this macro for constants.
Pick-to: 6.5
Change-Id: Id2ca3f6e4ffb1caf23cb7a38205dfcc8a7e7dee4
Reviewed-by: Paul Wicking <paul.wicking@qt.io>
Reviewed-by: Topi Reiniö <topi.reinio@qt.io>
|
|
|
|
|
|
|
|
|
|
|
|
| |
The main goal is to make the code easier to read and check.
This way, a bug was found: a reversed condition. Extensions
are not supposed to be enabled by default, but still were
for parts of the documentation.
Pick-to: 6.5
Change-Id: I5425c658d8f8adb368a12967a679b0c09851cf6a
Reviewed-by: Topi Reiniö <topi.reinio@qt.io>
Reviewed-by: Paul Wicking <paul.wicking@qt.io>
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
| |
QDoc's \brief command takes an entire paragraph as its argument, and
also allows for the processing QDoc commands or macros that appear in
the argument. Due to QDoc's internals, this may lead to a situation
where such commands consume newline characters that the \brief command
relies upon as indicator of its end condition, leading to a situation
where the \brief command erroneously includes the following paragraph
as part of its argument.
In particular, this may cause issues for certain commands that
"naturally" fit in a document "header". For example, given the
following content in a .qdoc file:
/*!
\page the_page.html
\title The title
\brief This is the brief.
\keyword the_keyword
Lorem ipsum dolor sit amet.
Santa Mozzarella!
*/
the brief will contain:
This is the brief. Lorem ipsum dolor sit amet.
And the only content in the generated output will, unexpectedly, be
Santa Mozzarella!
Due to its design, modifications to the \brief command are difficult,
as they will inevitably change QDoc's behavior significantly, with the
possibility of silent breakage. Therefore, enforce that the \keyword
command starts ends the paragraph it occurs in before further
processing.
This change includes a reproducing test case for the behavior in
question, which serves to validate the fix as well as as a guard for
future regressions.
Fixes: QTBUG-70959
Change-Id: I8f5b8a4aebf2ed2040bf43c1d4551ec280fc895a
Reviewed-by: Topi Reiniö <topi.reinio@qt.io>
|
|
|
|
|
|
|
| |
Task-number: QTBUG-113116
Pick-to: 6.5
Change-Id: I5ea9291d8ca4dce13a26d1d70874223e63a09671
Reviewed-by: Joerg Bornemann <joerg.bornemann@qt.io>
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
| |
QDoc already allows defining a custom status for C++ and QML modules
via the \modulestate command. In Qt, this is typically used for
marking a module and its types with 'Technology preview' status.
Allow a custom status for individual types as well, with
\meta {status} {<description>} command. This information is added
to the 'Requisites' table on top of the type reference page.
Document the new status argument for \meta, and update its
documentation as it contained obsolete information.
Pick-to: 6.5
Task-number: QTBUG-113026
Change-Id: I5a13aa8650b6e188ffe50a1e948da90474bfb7a0
Reviewed-by: Luca Di Sera <luca.disera@qt.io>
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
| |
QDoc provides various ways to document the status of an entity;
\deprecated, \preliminary, and \modulestate commands. These
commands produce a brief sentence describing the status, however,
for C++ and QML types, a logical place for this information is
also the 'requisites' table at the start of the page.
Having the status information in the table makes it more
apparent for the reader that they're looking at documentation
for a deprecated or preliminary type. For HTML generator, this
commit also adds a <span> element that allows additional
visuals via CSS (e.g. an icon) for a specific status.
Pick-to: 6.5
Fixes: QTBUG-113026
Change-Id: If38a6d51631277a0d98b2cb702acf2598b694643
Reviewed-by: Luca Di Sera <luca.disera@qt.io>
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
| |
The transmogrify() function was used by the Generator to produce
clean output file names by replacing all non-alphanum characters
with hyphens. This function is useful elsewhere as well,
especially in HTMLGenerator, as it produces valid strings for use
as HTML attribute values.
Rename the function to a more descriptive canonicalizeFileName(),
move it to the Utilities namespace, improve its documentation and
touch up the implementation a bit; make it return a QString
instead of modifying a string passed as an argument.
Pick-to: 6.5
Change-Id: I6088f4603802b86f96c4a5b668668ef229b302f3
Reviewed-by: Luca Di Sera <luca.disera@qt.io>
|
|
|
|
|
|
|
|
|
| |
The entire method sits behind an `if`. Inverse the logic of the
conditional and return early. This allows for flattening the whole
method.
Change-Id: I849f089bf4c84b4715eaeb0d2863f7c6fff24c96
Reviewed-by: Luca Di Sera <luca.disera@qt.io>
|
|
|
|
|
|
|
|
|
| |
The entire method sits behind an `if`. Inverse the logic of the
conditional and return early. This allows for flattening the whole
method.
Change-Id: I611a69bfd8850ff59e726b10d22801a3fac0527f
Reviewed-by: Luca Di Sera <luca.disera@qt.io>
|
|
|
|
|
|
|
| |
Pick-to: 6.5
Change-Id: Ied11784e840d03542a5db281590729838ed625c3
Reviewed-by: Jarek Kobus <jaroslaw.kobus@qt.io>
Reviewed-by: Qt CI Bot <qt_ci_bot@qt-project.org>
|
|
|
|
|
|
|
|
|
|
|
| |
Before, lrelease reported only the line number of the first of
duplicated messages. To actually resolve the duplicates the user must
know the occurrences of all duplicated messages.
Now, lrelease reports the line numbers of all duplicated messages.
Change-Id: I19836f54dcaa9b1d22a9e3e708f830769c50bff2
Reviewed-by: Kai Köhne <kai.koehne@qt.io>
|
|
|
|
|
|
|
|
|
| |
It seems the Qt Network libraries are not required for the Help module,
nor the qhelpgenerator tool.
Change-Id: I4c08c052a6daa62e65357ecc1f452ee150cd6172
Reviewed-by: Qt CI Bot <qt_ci_bot@qt-project.org>
Reviewed-by: Kai Köhne <kai.koehne@qt.io>
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
| |
The command \details generates a collapsible <details>
element with a <summary> to control the hidden/visible
state.
The idea behind this is to provide more information with
less text on our main pages.
For output formats other than HTML, the details are
rendered as a normal paragraph and the summary string
is ignored.
Pick-to: 6.5
Change-Id: Id5daddd4854f22b9ceaa9a55b98af94a1ba06039
Reviewed-by: Paul Wicking <paul.wicking@qt.io>
|
|
|
|
|
|
|
| |
Pick-to: 6.5
Task-number: QTBUG-112841
Change-Id: I1d7f394c52f609302711da2dcd71df9fe8ad8e88
Reviewed-by: Joerg Bornemann <joerg.bornemann@qt.io>
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
| |
Projects with cmake_minimum_required(VERSION 3.19) or below, so with
no support for the CMP0118 policy, failed to configure when
translations were added in a subdirectory scope different from
the target scope.
qt_add_translations adds qm files to resources, that in turn calls
_qt_internal_expose_deferred_files_to_ide which adds the qm files
to the target sources.
Because qm files are created using add_custom_command, which by default
marks the files as GENERATED only in the directory scope of the
command (unless CMP0118 is set to NEW), that causes add_executable to
think the qm files are not generated, and error out with
"Cannot find source file:".
Explicitly set the GENERATED flag in the target directory scope to
avoid the issue when using CMake 3.18+.
The error still happens with CMake 3.17 or lower, but that's not the
only error that happens. Just adding resources in a different
subdirectory without exposing the source files already fails, and
that's not something we can really fix without a newer CMake version.
Pick-to: 6.5
Fixes: QTBUG-112841
Change-Id: I79eced94ac641a6f9239f3eb721cef5e35f847fa
Reviewed-by: Joerg Bornemann <joerg.bornemann@qt.io>
Reviewed-by: Amir Masoud Abdol <amir.abdol@qt.io>
|
|
|
|
|
|
|
|
|
| |
Moving the QT_END_NAMESPACE before the #endif of the include guard.
Pick-to: 6.5
Task-number: QTBUG-109394
Change-Id: I13f8e71aca28b8dacbe00d7006f4e7ef807a9904
Reviewed-by: Alexandru Croitor <alexandru.croitor@qt.io>
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
| |
QDoc includes a number of attributes when generating index files.
Internally, QDoc uses the `FunctionNode` data structure to represent
invokables. This data structure includes the return type for the
function or method such a node represents. However, not all invokable
entities that are represented internally as a `FunctionNode` carry a
return value. This applies in particular to preprocessor macros in C
and C++.
When generating the index files. QDoc writes an empty `type=""`
attribute for `FunctionNode`s that represent a macro. When reading
the values back in, the value for the `type` attribute defaults to
empty is the attribute is missing. Therefore, writing this out in the
first place leads to unnecessary clutter in the index files.
This change modifies QDoc's behavior such that these attributes are only
written to the index file if they exist. Test data for the
`generatedOutput` test is updated to reflect the new content of the
index files covered by that test.
Task-number: QTBUG-112494
Change-Id: Id6e3a730cbde098068029af1ebf9fa17bd2a4441
Reviewed-by: Topi Reiniö <topi.reinio@qt.io>
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
| |
QDoc offers the `\qmltext` and `\endqmltext` command pairs, dating back
to sometime prior to when QDoc moved to qttools.git in 2015.
The commands have since been considered tags not to be handled
specifically when generating documentation. The commands have not been
documented.
Upon inspection of source code across Qt and its modules, no usage of
the commands have been found, with the exception of the generated
output test for QDoc itself.
Even though unused and considered "only tags", the `Generator`,
`HTMLGenerator`, and `DocBookGenerator` classes still implement methods
to handle them and generate output for them. The removal of the
commands therefore necessitates removal of the methods that deal with
them. As the command pair is unused, removing the related code is a way
to reduce the surface of QDoc's generator classes, making them slightly
better suited for testing. This also improves the maintainability of
QDoc.
This change thus removes the commands and the related `Atom`s, as well
as any method designed to deal with those `Atom`s. In addition, the
test data and expected output for the generated output test is modified
to accommodate the behavior change.
Fixes: QTBUG-112764
Change-Id: I2b0a57783ccdccd3e8c1693e6946ecf07777f3b6
Reviewed-by: Luca Di Sera <luca.disera@qt.io>
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
| |
When the WebXML generator was revived in 2017, a case for handling QML
atoms in the method `WebXMLGenerator::addAtomElements` was added under
an `#ifdef QDOC_QML` guard. This is, according to esteemed historians,
a remnant from the old Qt 4.7 implementation of the WebXML generator.
However, since the revival, the define wasn't ever set by anything in
neither QDoc nor the build system, effectively rendering this code
unreachable.
This change removes the `#ifdef [...] #endif` block, as removing the
unused code won't lead to behavior change of QDoc.
Task-number: QTBUG-112764
Change-Id: Ib9b50d4831e86c60de05065d315f421ae2289f64
Reviewed-by: Luca Di Sera <luca.disera@qt.io>
|
|
|
|
|
|
|
|
|
|
|
|
| |
"qa-table.png" is currently unused in the containing documentation.
Supposedly it showed an old feature of QDoc that is now not available
anymore.
Hence, it is now deleted.
Change-Id: I043f718a0f298d4f57e1bf897ab6d51fd51eee88
Reviewed-by: Paul Wicking <paul.wicking@qt.io>
|
|
|
|
|
|
| |
Pick-to: 6.5
Change-Id: If0aff3c1a767e6830f5480f57dfe82a66feb124c
Reviewed-by: Jarek Kobus <jaroslaw.kobus@qt.io>
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
| |
QDoc development under the "qttools" repository is currently performed
under the "src/qdoc" directory, which contains all source files and
directories relevant to QDoc as direct children.
Due to a slow restructuring of how QDoc works, what its dependencies are
and certain possible architectural changes, the infrastructure that is
expected to be required for the development of QDoc might increase.
Some of that infrastructure, which might require some custom effort, is
expected to be developed as "independent" "library-like" sub-projects,
which QDoc depends on.
Albeit developed "independently", such infrastructure would be developed
specifically for QDoc and thus should live "adjacent" to it.
To allow such a structure a new "qdoc" directory was added under the
"src/qdoc" directory. All source files and directory that were
previously children of the "src/qdoc" directory were moved under the new
"qdoc" directory.
This preserves the space for QDoc-related elements and the relative
project structure while allowing some space for "adjacent" projects that
are intended for QDoc specifically.
To support the change, a new "CMakeLists.txt" file was introduced under
"src/qdoc", which dispatches to the "CMakeLists.txt" file in the new
"src/qdoc/qdoc" directory.
QDoc is only built when certain dependencies are found. This is
supported through the use of Qt features at the CMake level.
The "CMakeLists.txt" file in "src", thus dispatched to the "src/qdoc"
directory only when the required features were found.
As "independent", "library-like", entities might not have the same
requirements as QDoc, the "CMakeLists.txt" file in "src" was modified to
always dispatch to the "src/qdoc" directory while the features-check was
moved to the new "CMakeLists.txt" files in "src/qdoc", so as to allow
non-QDoc but QDoc-specific project to have an independent configuration
for building.
Certain test projects in "test/auto/qdoc/" depends on QDoc-specific
source-files to generate their CMake targets.
Those dependencies were generally specified as relative paths.
The additional level in the directory structure invalidated the paths
and, hence, the relevant "CMakeLists.txt" files for those projects were
modified to correctly refer to the new directory structure.
Change-Id: I50c7106614428753544eaba5091e1e44d48fd31d
Reviewed-by: Topi Reiniö <topi.reinio@qt.io>
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
| |
The \generatelist command already supported listing members of a group
as a simple unordered list of titles/links, but the links were broken
as they always referred to the current document.
In DocBook generator, reuse generateAnnotatedList() for this purpose
as it already has support for outputting simple itemized/unordered lists.
Create a new private enum GeneratedListType to select the list 'subtype'
and clean up the API.
Add simple test case and documentation of the new argument.
Fixes: QTBUG-111575
Pick-to: 6.5
Change-Id: I30e4976cef3b6aa5414aac457844ae5bc0762f3d
Reviewed-by: Paul Wicking <paul.wicking@qt.io>
|