| 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>
|
| |
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
| |
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>
|
| |
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
| |
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>
|
| |
|
|
|
|
|
|
|
|
| |
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>
|
| |
|
|
|
|
|
|
|
|
|
| |
Explicitly test that the right tags are output when the DocBook 5.2
extensions are enabled. This test suite is made small intentionally,
because the extensions do not have an impact on that many pages.
Pick-to: 6.5
Change-Id: I6a135ddb20f17034287e0a6d5da4a5b96e064028
Reviewed-by: Topi Reiniö <topi.reinio@qt.io>
Reviewed-by: Paul Wicking <paul.wicking@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>
|
| |
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
| |
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>
|
| |
|
|
|
|
|
|
|
|
|
| |
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>
|
| |
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
| |
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>
|
| |
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
| |
QDoc tests are organized into a series of different projects under the
"tests/auto/qdoc" directory.
Many of those projects uses a subset of QDoc source and header files to
perform tests on a subset of QDoc functionalities.
The CMake target description for those projects refers to those required
files through the use of relative paths, going back up and down the
filesystem structure to the "src/qdoc" directory and the files
themselves.
Due to a recent change in QDoc directory structure, those relative paths
were broken, breaking the tests as a consequence, thus requiring
modification to test projects' "CMakeLists.txt" files to align to the new
structure.
While we don't expect QDoc directory structure to change often, we can
reduce the friction of doing so in the future by centralizing the
definition for the base path of those relative paths.
To do so, "tests/auto/qdoc/CMakeLists.txt", the "parent"
"CMakeLists.txt" file to QDoc's test projects, was modified to provide
two variables, `QDOC_SOURCE_DIRECTORY` and `QDOC_INCLUDE_DIRECTORY`.
Both variable refer to a suitable path that can be used as the base for
finding source file and header files, respectively.
The "CMakeLists.txt" files for the affected test projects were modified
to use `QDOC_INCLUDE_DIRECTORIES` in the `INCLUDE_DIRECTORIES` property
for their test target, replacing the relative path to the QDoc source
directory.
Similarly, they were modified to use "QDOC_SOURCE_DIRECTORY" as the base
path for the inclusion of C++ source files under the `SOURCES` property
of their test target.
Some of the test project target included certain used headers files
under their `SOURCES` property.
As the availability of those headers is implicit under the provided
`INCLUDE_DIRECTORIES` property of the target, all paths to headers files
were removed from under the `SOURCES` property.
Albeit a restructuring such as the one that was performed would still
break the tests configuration, having a single place of failure to
change is expected to alleviate the issue.
Change-Id: I9f0bd42a61a7dd436d70e19e7d38820bf9b54662
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 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>
|
| |
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
| |
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>
|
| |
|
|
|
|
|
|
|
|
|
|
|
|
|
| |
This reverts commit df735050ecd01687f17df8f161c706541319ad05.
While the commit works, it introduces unnecessary complexity to the
processing of the \meta command. The same functionality can be
achieved with the help of a documentation macro.
The commit did contain a bug-fix for the \generatelist command,
which is re-introduced as a separate change.
Pick-to: 6.5
Change-Id: Ie8578baa35cfee210fc52428c610307f51103d22
Reviewed-by: Paul Wicking <paul.wicking@qt.io>
|
| |
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
| |
`WebXMLGenerator::startLink` is responsible for writing the WebXML tags
for links. The method takes a pointer to `Atom`, from which a string is
obtained for use in parts of the output. In most locations, the callee
pre-qualifies the validity of the pointer it passes to the method
(e.g. `if (atom) startLink([...]`).
However, there's an exception to this in
`WebXMLGenerator::generateAnnotatedList`, which calls
`Text::firstAtom()` -- that may return `nullptr` -- in the call to
`startLink`. This is considered a valid use-case that occurs when
there's only title/meta commands and no body in the documentation.
In such a case, or if the string obtained from `Atom::string()` is
empty, `WebXMLGenerator::startLink` is designed to fall back to the
full name of the `Node` being processed. However, in the case when
generating a link for an example, `Generator::exampleFileTitle()` is
called to obtain a file name for the example, and the `Atom*` is
dereferenced to obtain a string is input for the latter method. At
that point, the `Atom*` may be an unguarded null pointer.
This change updates the generatedOutput test for QDoc by adding a
minimal documentation project that serves as means to reproduce a bug
that was observed in Qt3D, and fixes the bug in QDoc. The documentation
project is designed such that the preconditions outlined in the first
paragraph are met; that is to say, the structure of the documentation
is such that, for an `Atom` that's constructed while generating the
documentation set, `Atom::firstAtom()` is going to return a null
pointer. The change to the test serves to validate the bug fix as well
as to guard for future regressions.
Avoid the crash that would occur when dereferencing this null pointer
in `WebXMLGenerator::startLink` by checking the validity of the `Atom*`
before dereferencing it to obtain a string used as file title when
generating a link for an example.
Fixes: QTBUG-112641
Pick-to: 6.5
Change-Id: I3633e5473b60013968becac4cd7bdacdbbdcb9ff
Reviewed-by: Topi Reiniö <topi.reinio@qt.io>
|
| |
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
| |
QDoc includes a number of attributes when generating index files.
Some of these include the default value the attribute has when reading
the index files back in, such that the overall effect of writing them to
the index file in the first place is none at all for QDoc.
For example, for a function that isn't virtual, const, static, final, or
overridden, the index file contains the attributes
virtual="non" const="false" static="false" final="false" override="false"
This change modifies QDoc's behavior such that these attributes are only
written to the index file if they are true. This reduces the size of the
index files generated for Qt by approcimately 7.16%. Test data for the
generatedOutput test is updated to reflect the new content of the index
files covered by that test.
[ChangeLog][QDoc][Index files] QDoc no longer writes the attributes
virtual, const, static, final, or override, to the index files, unless
the attribute is part of a function or method's signature. This reduces
the file size of index files somewhat.
Fixes: QTBUG-112494
Change-Id: I7d25dc429749dd29dbdcd65b7ca78a51ced5dd0f
Reviewed-by: Topi Reiniö <topi.reinio@qt.io>
|
| |
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
| |
The fix for QTBUG-73273 already added code to allow prefixed raw string
literals. Now, lupdate supports regular prefixed string literals as
well.
If the parser encounters a prefixed string literal, ignore the prefix
and handle the rest as ordinary string literal.
Note that expressions like tr(U"foo") won't compile out of the box. We
support them nevertheless. The user might provide their own tr macro
that handles such string literals.
[ChangeLog][lupdate] lupdate now supports prefixed string literals like
u"foo".
Pick-to: 6.5
Fixes: QTBUG-59802
Change-Id: Ibe8b4b83ee1197a73678b1e8f37dd6ac7db57714
Reviewed-by: Kai Köhne <kai.koehne@qt.io>
|
| |
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
| |
There's an edge case in the number heuristics of lupdate that triggers a
Q_ASSERT due to an out-of-bounds string character access. To run into
the assert, the following must be true:
- oldSource == oldTranslation
- oldSource must contain a number followed immediately by more than one
characters
- oldSource and newSource must differ only in the character after the
number
Examples that trigger the assert:
| oldSource | newSource |
|------------+------------|
| "%1MiB" | "%1Kib" |
| "1Mi" | "1Ki" |
| "1M " | "1Ki " |
| "123abcde" | "123xbcde" |
Examples that do not trigger the assert:
| oldSource | newSource |
|------------+------------|
| "%1MiB" | "%1Kob" |
| "1M" | "1K" |
| "123abcde" | "123xxcde" |
Add a test case that triggers the Q_ASSERT.
Add a check to avoid the out-of-bounds access as a minimal fix. The
whole number heuristics algorithm is fishy and produces results that
don't match the source code comments. But it's been like that "forever",
so let's not change existing behavior people may rely on.
Pick-to: 6.5
Fixes: QTBUG-111775
Change-Id: Ibb6bcce9115f7060b6de3f97451e38105623c003
Reviewed-by: Kai Köhne <kai.koehne@qt.io>
|
| |
|
|
|
|
|
|
|
|
| |
The enum class construct can only be based on an integral type so they
can be skipped over safely.
Pick-to: 6.5
Task-number: QTBUG-36589
Change-Id: I9a7dd7508f80002e9e46429de726a75607d21a54
Reviewed-by: Joerg Bornemann <joerg.bornemann@qt.io>
|
| |
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
| |
Examples in the Qt codebase are now tagged with specific categories,
using the '\meta category {Category}' command. To easily generate
lists of members in each category, add support for a 'category'
argument in the \generatelist command.
Internally, utilize the mechanism already provided by \ingroup command,
by adding the node to an internal group prefixed by 'category', when
processing the '\meta category' command.
\generatelist already supported listing members of a group as a simple
unordered list of titles/links. Fix the generated links as they were
broken, always referring to the current document.
In DocBook generator, reuse generateAnnotatedList() 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.
Pick-to: 6.5
Fixes: QTBUG-111891
Fixes: QTBUG-111575
Change-Id: Icd5647a09b9ae8cb0ac243fa49d3d99263d397cb
Reviewed-by: Paul Wicking <paul.wicking@qt.io>
Reviewed-by: Nicholas Bennett <nicholas.bennett@qt.io>
|
| |
|
|
|
|
|
|
|
| |
Streamline Aggregate::findAllSince() and stop it from generating items
marked with \dontdocument command; these resulted in broken links if a
dont-document class uses a \since command.
Change-Id: I1d06e3c846c206cdc54edb9e1fe9b1b8b105b544
Reviewed-by: Luca Di Sera <luca.disera@qt.io>
|
| |
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
| |
The output of \sincelist command lists enumerations introduced in a
specific version, documented with \enum with an associated \since
meta-command. Individual enum \value entries can also be marked with
a since-clause, however, this information was missing from the
generated list.
Adding support for this is less than trivial because EnumItem is not
a Node subclass, and the Sections class, which is responsible for
distributing the entries displayed in a since-list, operates on
Node instances. To work around this,
* Introduce since()/setSince() to EnumItem
* Resolve since info for enum values in Tree::resolveSince()
* Add enum values to a dedicated map in QDocDatabase
* Add enum value since attributes to .index file
* Add 'New Enum Values' as a new Section entry
In order to generate content for the new section, don't directly
populate it; only add a single entry to mark it non-empty. Actual
enum values are then fetched from the new 'since-map'. Entries in
this map contain a pointer to the associated EnumNode, used for
linking.
Add a simple test case in generatedoutput autotest.
Fixes: QTBUG-110781
Change-Id: I064446dc1e369013284ba934adeabe908754b3bb
Reviewed-by: Luca Di Sera <luca.disera@qt.io>
|
| |
|
|
|
|
|
|
|
|
|
|
|
| |
So far we only supported \meta tag {}, even for multiple tags. This is
confusing, so allow both 'tag' and 'tags' synonymously.
Pick this also to 6.5, cause quite some examples in various repositories
contain "\meta tags".
Pick-to: 6.5
Change-Id: I2d0e59b4a0de27aa5f045b4d5f981c47aaf8b98c
Reviewed-by: Qt CI Bot <qt_ci_bot@qt-project.org>
Reviewed-by: Topi Reiniö <topi.reinio@qt.io>
|
| |
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
| |
Since C++14, single quotes can appear in integer literals as separators
to improve readability.
When quoting a file that contains such a literal, QDoc interpreted the
single quote as a delimiter for a char, and kept reading ahead for the
closing quote. This interfered with correct marking up of C++ code and
ultimately caused a warning:
(qdoc) warning: Something is wrong with qdoc's handling of marked code
as the plain code and marked-up code end up having different number of
lines.
Pick-to: 6.5
Fixes: QTBUG-111973
Change-Id: Icd2d95973f9cee72eb1c9e3f2d79df0af643dbaa
Reviewed-by: Paul Wicking <paul.wicking@qt.io>
|
| |
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
| |
Config class now provides Config::get(), returning a
ConfigVar reference which can be further converted
to string, list, set, int, or bool. Use get()
throughout the codebase and remove the old access
functions.
In addition, make Config::get() return a const
reference, and prevent an unnecessary contains()
check by using an iterator.
Do some drive-by cleaning of related code.
Change-Id: I2ff2203824cd4ae80c4615080948565219ad20b2
Reviewed-by: Paul Wicking <paul.wicking@qt.io>
Reviewed-by: Luca Di Sera <luca.disera@qt.io>
|
| |
|
|
|
|
|
|
|
|
|
|
|
|
|
|
| |
A meta description is an HTML element that provides a brief summary of
a web page, typically displayed as part of a search engine results
page.
Use the \brief description for pages that have it. This should cover
virtually all of the API reference as type \brief appears on module
pages and therefore is rarely missing. Many overview \page's have it
as well.
Pick-to: 5.15 6.2 6.4 6.5
Fixes: QTBUG-111360
Change-Id: Ie403777fd895a995bbd7d717333e95c1b6b77d89
Reviewed-by: Kai Köhne <kai.koehne@qt.io>
|
| |
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
| |
Serves as an indicator in the release process that these components need
to be carefully monitored and updated (even more often than the other
third-party modules).
So far this is not reflected in the generated documentation. This might
change in the future though.
For reasoning, see also
https://lists.qt-project.org/pipermail/development/2023-February/043667.html
Pick-to: 6.5
Change-Id: I82c59e0198fc2fdc855aed89aa49f929391aa0ef
Reviewed-by: Qt CI Bot <qt_ci_bot@qt-project.org>
Reviewed-by: Joerg Bornemann <joerg.bornemann@qt.io>
Reviewed-by: Volker Hilsheimer <volker.hilsheimer@qt.io>
|
| |
|
|
|
|
|
|
|
|
| |
Allows to have text in extra comment within quotes that will be kept
intact when running lupdate.
Fixes: QTBUG-110630
Co-authored-by: Kai Köhne <kai.koehne@qt.io>
Change-Id: I267e779193f168a8af067b927735991f2c512145
Reviewed-by: Joerg Bornemann <joerg.bornemann@qt.io>
|
| |
|
|
|
|
| |
Pick-to: 6.5
Change-Id: Ic00df7d45246270d724b3b1d1ef9d13d76dcc136
Reviewed-by: Alexandru Croitor <alexandru.croitor@qt.io>
|
| |
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
| |
By default, QDoc printed progress information such as
qt.qdoc: Start/Stop qdoc for <project> in <mode>
qt.qdoc: Parse source files for <project>
These do not provide much useful information, so hide them under the
--log-progress command line option. --debug now also implies
--log-progress.
Remove all uses of leftover debug statements that used qDebug(), or
where suitable, convert them to use logging category with qCDebug()
and friends.
Remove unused function FunctionNode::debug().
Clean up formatting and language for some of QDoc's output messages
in passing.
Fixes: QTBUG-110923
Pick-to: 6.5
Change-Id: I2cab456b0e144249e4234a253fd1c90d76666132
Reviewed-by: Topi Reiniö <topi.reinio@qt.io>
|
| |
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
| |
This allows grouping an example into one or many categories, to be used
by Qt Creator to structure the Qt examples in the Melcome mode.
\example My Example
\meta category {My Category}
in the <example> section of the respective examples-manifest.xml file.
Pick-to: 6.5
Fixes: QTBUG-108930
Change-Id: Ia0c564dfd58e6e1b1982255607e867f5dcd2bdb9
Reviewed-by: Tuukka Turunen <tuukka.turunen@qt.io>
Reviewed-by: Leena Miettinen <riitta-leena.miettinen@qt.io>
Reviewed-by: Topi Reiniö <topi.reinio@qt.io>
|
| |
|
|
|
|
| |
Pick-to: 6.5
Change-Id: Ib52412754f1bba53e3cd16c5aa51716e2679c0e7
Reviewed-by: Friedemann Kleint <Friedemann.Kleint@qt.io>
|
| |
|
|
|
|
|
|
|
|
| |
The separation between 'examples' and 'demos' is not used anymore.
Also, Qt Creator since quite a long time does just read both files,
and treat them exactly the same.
Pick-to: 6.5
Change-Id: I307b32f1c87c849b0b8a1e19d7604fbbd5989d1f
Reviewed-by: Topi Reiniö <topi.reinio@qt.io>
|
| |
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
| |
C++'s allows certain declarations to be marked by
the `noexcept` specifier, so as to signify that the element will not
throw any exception.
A `noexcept` specifier might be unconditional, such the the relevant
element is always to be considered "noexcept", or conditional, such that
the element is or is not "noexcept" based on the evaluation of a
compile-time, user-defined expression.
This information is important to the user of an API, as it may dictate
when and how they can use a certain element.
Nonetheless, up to now, QDoc would not treat the "noexcept" specifier,
such that this information was lost between source-code and
documentation.
To avoid the issue and ensure that users are given a way to discern
whether something is marked "noexcept" or not, QDoc will now "tag" a
relevant documentable element that is a callable, such as a C++ method,
as "noexcept" when the `noexcept` specifier appears in its
declaration or the element is implicitly noexcept (e.g destructors).
To store this information, `FunctionNode`, the internal representation
for "callable" documentable elements, such as a C++ constructor or
method, was modified to expose an optional string, `m_noexcept`, trough
the setter, `markNoexcept` and the getter, `getNoexcept`.
`markNoexcept` allows the element as being "noexcept". Optionally a
string can be provided which represents the expression of a conditional
"noexcept".
`getNoexcept` returns an optional value. If the value is Nothing, the
element is to not be considered "noexcept".
If the value is Just, it will contain a string that represents the
condition under which the element is "noexcept".
An empty string is to be considered marking a non-conditional
"noexcept".
Generally, this kind of information is extracted from the codebase in
`ClangCodeParser::processFunction`, where an instance of a
`FunctionNode` is populated based on the Libclang-provided `CXCursor`
that generated it.
LibClang has only partial support for the `noexcept` specifier. It
allows the extraction of a `CXCursor_ExceptionSpecificationKind`, which
provides information about the present or not of a `noexcept` specifier,
but it doesn't provide a direct way to extract the
expression of a conditional `noexcept` specifier.
The expression of a conditioanl `noexcept` specifiers should generally
be, in some way, presented to the user, as the user would not otherwise
be able to ascertain whether an element is "noexcept" or not in its use
case, thus requiring us to extract it in some way.
For similar issues, we have generally taken to tokenizing the source
code to manually extract the required information.
For the specific case of a `noexcept` specifier, we consider this
unfeasible due to grammar of of the C++ language.
In a function signature, in particular due to the existence of the
`noexcept` operator, an operator that returns whether an expression is
"noexcept" or not, the `noexcept` keyword can appear many times, in many
places with different meanings.
The extraction of the very specific `noexcept` specifier, and its
expression should it be conditional, is thus hindered so that it is not
easy to cover all possible cases without actually parsing the signature
itself.
To be able to find the information we are looking for, we drop down from
LibClang's to clang's C++ AST, which provides full support for this kind
of extraction.
To do so, a new function, `get_cursor_declaration`, is added to
"src/qdoc/clangcodeparser.cpp".
Each `CXCursor` in LibClang stores a reference to the C++ AST element
that generated it.
`get_cursor_declaration` extracts this information, for CXCursors that
represent a declaration, and returns the underlying C++ AST node, which
can be used to access the more thorough functionalities that the C++ AST
provides.
`ClangCodeParser::processFunction`, was modified to call
`get_cursor_declaration` for its processed elements.
From the retrieved declaration, the normal methods of the C++ AST are
used to extract information about the presence, or lack thereof, of a
`noexcept` specifier and its expression, should it be conditional.
This information is then stored into the processed `Node`, using the
newly introduced `markNoexcept`.
Later on, during the "Generation Phase", where QDoc destructures the
provided documentable elements to produce the final output
documentation, QDoc will call a `CodeMarker` to generate the set of
"tags", small strings that appear near the detailed documentation of an
element, to enhance the final documentation with certain information
about the documented element.
To make use of the now stored "noexcept" information,
`CodeMarker::extraSynopsis`, which is the particular methods that
generates the relevant set of "tags" for an element, was modified to
take into account the "noexcept" information of a `FunctionNode`.
If the `FunctionNode` is marked as "noexcept" a tag will be produced.
If the "noexcept" is not conditional, a "noexcept" tag is produced.
If the "noexcept" is conditional, a "noexcept(...)" tag is produced.
When this is the case, additional information will be generated for the
detailed documentation of the relevant element to provide more
information about the conditionality of the "noexcept".
That is, a not will be produced that contains the expression that the
"noexcept" is conditioned on.
To do so, a new method `generateNoexceptNote` was added to `Generator`,
the base class of the components that take care of producing the
effective output during a QDoc execution.
The method is implemented using the same pattern of similar procedures,
such as `Generator::generateSince`, where, starting from the processed
`Node`, a `Text`, an internal representation for certain formatted
output, instance is produced and delivered to `Generator::generateText`,
which takes care of producing the marked-up output documentation.
In particular, a note element containing the extracted conditional
expression and a small text about the lack of exceptions depending on
this expression is produced.
`HtmlGenerator`, the child class of `Generator` that specifically
generates the HTML formatted output documentation, was modified to call
the `Generator::generateSince` method when producing the detailed
documentation of an element.
The conditional expression for a `noexcept` specifier, while necessary
for the user to see, might not necessarily be legible without additional
context.
This context cannot generally be auto-generated and, thus, the specific
format in which we present this information is not to be considered
final and is expected to change in the near future.
When QDoc parses the source code for a project, it generates an
XML-based "index" file, containing certain information about the
extracted documentable elements that can be consumed by external tools
and is consumed by QDoc itself to enable cross-module linking.
To allow the newly added "noexcept" information to be retained between
modules and to enable the inspection of such information for external
consumers, `QDocIndexFiles::generateFunctionSection`, which writes the
relevant information about a `FunctionNode` in the index file, was
modified to write a "noexcept" attribute in the XML-element
representing the `FunctionNode`.
The attribute is elided when the `FunctionNode` is not marked as
"noexcept", the default state, to save space and avoid cluttering the
output.
If the "noexcept" is conditional, a further attribute,
"noexcept_expression" is written, containing the extracted conditional
expression of the "noexcept".
Similarly, `QDocIndexFiles::readIndexSection`, which retrieves the
information stored in a certain index file and rebuilds the internal
representations that QDoc uses for the represented elements, was
modified to read the "noexcept" and "noexcept_expression" attributes that
were added.
If the "noexcept" attribute is present and has a "true" value in a "function"
element, the reconstructed `FunctionNode` will be marked as "noexcept",
to retain the information.
If the "noexcept_expression" attribute is present, the `FunctionNode`
will further contain a copy of the conditional expression in string form.
The regression files for `tst_generatedOutput` were regenerated to take
into account the addition of the new tag.
Fixes: QTBUG-93439
Change-Id: Ic6e15c53309db6c4f398c15670fe3f15886bca3e
Reviewed-by: Qt CI Bot <qt_ci_bot@qt-project.org>
Reviewed-by: Topi Reiniö <topi.reinio@qt.io>
|
| |
|
|
|
|
|
|
|
|
|
|
|
| |
Inline images need not consider rest of the line
as alt text, unless they are wrapped in a {}.
Updated the qdoc manual to indicate that caption
to an inline image must be wrapped in braces.
Pick-to: 6.2 6.4 6.5
Done-with: Topi Reinio <topi.reinio@qt.io>
Change-Id: I2098e8da2e9139bc6c022f36aa8432913546e863
Reviewed-by: Topi Reiniö <topi.reinio@qt.io>
|
| |
|
|
|
|
|
|
|
|
| |
As we are now processing the arguments with
cmake_parse_arguments(PARSE_ARGV, we don't need to pass the escape
characters anymore.
Task-number: QTBUG-99238
Change-Id: I9c91e6d9678a87d7d5da1c36d72803f5e586513d
Reviewed-by: Alexey Edelev <alexey.edelev@qt.io>
|
| |
|
|
|
|
|
|
|
|
|
|
|
|
|
| |
Snippet marker tags must follow a QDoc-style comment sequence '//!' -
but there's no need to require these comments to start from the
beginning of the line.
Allow whitespace to appear before the comment by trimming the line
before comparison.
Pick-to: 6.5 6.4 6.2
Fixes: QTBUG-109735
Change-Id: I23e5703bdf518ecf8511075a295b3c404704a065
Reviewed-by: Paul Wicking <paul.wicking@qt.io>
Reviewed-by: Luca Di Sera <luca.disera@qt.io>
|
| |
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
| |
In .index files, a 'qml-module-name' attribute was incorrectly added
for QML (value) types that did not use the \inqmlmodule command.
Instead of omitting the attribute, its value was set to the name of
the type itself. This caused incorrect linking to
"<type>-qmlmodule.html" in some cases.
Drop the attribute for QML types that do not provide the module
information. Also drop it for QML modules as it's duplicate
information to the 'name' attribute.
Add a test for ensuring that autolinking to QML types loaded
from .index works correctly.
Pick-to: 6.4
Change-Id: Idb00999774eb2411f406148011e4542d8038c6cd
Reviewed-by: Luca Di Sera <luca.disera@qt.io>
|
| |
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
| |
QML value types, formerly known as basic types, are nowadays provided
by multiple modules and contain also properties and methods.
QDoc's support for value types was rather basic (pun intended):
No import/since statements nor sections for properties etc. was
generated, the reference page had essentially a flat structure
similar to a generic \page.
As QML and QML value types are closely related, eliminate the dedicated
Node subclass for value types (QmlValueTypeNode), handle both with
QmlTypeNode class, differentiating them only with NodeType enumeration.
Make Node::isQmlType() return true for both to provide similar behavior
for all QML types, with a few exceptions:
* Do not warn if \qmlvaluetype command is missing \inqmlmodule
info as many of the original value types do not document it
* Do not generate 'all members' file for value types as they're
not expected to inherit other types.
* Do not include the QML module name qualifier into the filenames
generated for value types. This is done in order to keep the
existing behavior for value types and to avoid creating
redirects for online documentation.
Related to the last point, remove code from
Generator::fullDocumentLocation() that was never executed as it was
a duplicate from Generator::fileBase().
Unifying the types under a single Node subclass allows for removal of
multiple functions and code paths related to value types. They have
some constraints compared to proper QML types, but QDoc does not
currently enforce them.
[ChangeLog][QDoc][QDoc now properly outputs documentation for QML
value types with properties and methods.]
Pick-to: 6.4
Fixes: QTBUG-109132
Change-Id: I418660b0a6e0461c82fd5cb67e4f955a0d9a712c
Reviewed-by: Topi Reiniö <topi.reinio@qt.io>
|
| |
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
| |
QDoc uses a pair of classes `Sections`/`Section` that destruct and
categorize the members of an `Aggregate`, an internal representation for
documentable elements that are composed of multiple documentable
elements, to generate a series of ordered lists in the output
documentation.
For example, the list of members of a C++ class in the reference page of
that same class.
Internally, a `Section` categorizes the "children" of an `Aggregate` by
using a series of maps, to provide an ordering, that are later
"flattened" into ordered, sequential, monodimensional-structures,
generally vectors, that are presented to the consumer of a `Section`,
mostly the `Generator`s that actually produce the output documentation,
to iterate over the categorized elements.
The keys of the internal maps are never used by consumers of a
`Section`, such that their only purpose is to internally provide an
ordering before they are "flattened".
Hence, the maps can be removed, with the intermediate flattening step,
in favor of directly constructing the same monodimensional-structures,
which can be sorted directly, before being presented to a consumer, to
produce the same result.
`Section::m_memberMap`, is one such map that is used to hold all the
elements of a destructured `Aggregate`, without categorization and is
now removed as it is unnecessary.
Further to removing the member variable, all insertion into the map were
converted to insertion into `Section::m_members`, the flattened version
of the map.
`Section::insert/2`, which inserted an element with a certain key into
the `Section::m_memberMap` was removed as it lost its purpose.
`Section`s are statically allocated in `Sections`, which act as a
container of `Section`, and are reused between instances of `Sections`.
To support this structure, `Section` provides a `clear` method, which
cleans the internal state, such as the internal maps, to prepare the
`Section` instance for reuse.
The clearance of `m_memberMap` was removed from `Section::clear`, as the
member variable is not part of the internal state anymore.
As `Section` destructures an `Aggregate` into categories, not all of
which might be used depending on the structure of the specific
`Aggregate`, it provides a custom `isEmpty` method that specifies that
the `Section` is empty only if all of the internal containers for each
category is empty.
This method was changed to use `m_members` instead of `m_memberMap` to
check the emptiness of the "all members" category, as `m_memberMap` is
now removed in favor of `m_members`.
Each internal map is "flattened" in `Section::reduce`, which is called
after the `Aggregate` that a `Section` is destructuring is fully
categorized.
The code flattening `m_memberMap` was removed in favor of sorting
`m_members` at this step, after it is fully populated.
`Section` uses a free function in "sections.cpp", `sortName`, which
produces a series of orderable strings based on a `Node`'s, the base
class for a documentable element, name, that are generally used as keys
for the map, providing the specific ordering that QDoc currently uses.
To provide the same ordering, some temporary code was included as a
comparator that uses `sortName` as its base.
As `sortName` is relatively heavy, as it has to allocate a series of
strings so that they can be used as keys to the maps, the temporary
code, together with `sortName`, are later expected to be removed in
favor of a direct comparator that does not use intermediate strings,
when all internal maps are removed in favor of their flattened version.
It should be noted that, while the ordering uses the same methodology,
it will not be equivalent to the one provided by the map-based
implementation.
As `sortName` is not antisymmetric, certain elements are considered
equal, albeit they are not the same documentable element.
The ordering for such colliding elements is implementation dependent and
is inverted between the map-based version, which orders colliding
elements in reversed insertion order, and the "flattened" version, which
orders colliding elements in insertion order.
This affects many files in the output documentation, generally the
"members" file that QDoc produces for a C++ class, that lists all
elements of the class, inherited or not.
Furthermore, certain non-members file are affected.
QDoc identifies C++ methods or functions with the same name under the
same namespace as overloads.
It later marks them with an "overload number", a simple increasing
integer that is used to differentiate the various equally named elements.
`sortName` takes this overload number into account, so that different
overloads of the same element do not collide.
Nonetheless, there seems to be a bug where certain elements are not
correctly identified as overloads, producing the same `sortName` and
thus colliding.
C++ classes that have those colliding elements will see a difference in
their ordering.
Such an example are some of the "drawText" members in "qpainter.html".
In `Section`, not all elements would first pass by the internal map
before it was "flattened", instead having them directly inserted in the
"flattened" version, such that they would receive no sorting.
For example, elements of a `SharedCommentNode`, an internal
representation for elements that share a documentation block, would
behave this way.
As the sorting now happens directly on the "flattened"
`Section::m_members`, the groups of elements that are produced from
those `SharedCommentNode` will now provide an order.
Lastly, certain spurious changes are in effect due to this change.
Certain C++ classes' reference pages seems to not have any sorting.
For example, "qhashiterator.html", which is produced as the reference
page for `QHashIterator`, show such a behavior.
Such a bug would be caused by the elements of the `Aggregate`
representing the class being inserted directly into the "flattened"
version without passing for any internal map.
It is currently unknown why certain elements would follow this behavior
and the bug should be later addressed separately.
In the meantime, the ordering for those pages is now fixed, as the
sorting is provided directly on the flattened version.
The regression files for `tst_generated_output` were regenerated as they
were affected by the "all members" reordering.
Change-Id: Id7e02f944d2c987e726953f6eab96d3c96cbfbc0
Reviewed-by: Topi Reiniö <topi.reinio@qt.io>
|
| |
|
|
|
|
|
|
|
|
|
|
| |
- Auto links
- Qml property summary and method signature
- Anchors
- See also entries
- All C++ classes and QML types list
Task-number: QTBUG-106679
Change-Id: Ib7046321ccac16bf1141885a5cf2d411084f57ab
Reviewed-by: Topi Reiniö <topi.reinio@qt.io>
|
| |
|
|
|
|
|
|
|
|
|
|
|
| |
Replace a generic keyword that uses a QML module node \title with
a keyword that represents the actual QML module import:
QtQuick -> QML.QtQuick
QtQuick.Controls -> QML.Controls.QtQuick
Pick-to: 6.4
Fixes: QTBUG-105075
Change-Id: I78d05e9336dd9147e112fb99b1558fa7e07610c5
Reviewed-by: Kai Köhne <kai.koehne@qt.io>
|
