| Commit message (Collapse) | Author | Age | Files | Lines |
|---|
| |
|
|
|
| |
Change-Id: Ib09fb1c6e584401ab577de5c2e2f9b4f6fd2974b
Reviewed-by: Jani Heikkinen <jani.heikkinen@qt.io>
|
| |
|
|
|
|
|
|
|
| |
Signal arguments have proper types these days.
Fixes: QTBUG-109456
Change-Id: Ib545173f51723e652b574e19b2b6723fd00476ae
Reviewed-by: Friedemann Kleint <Friedemann.Kleint@qt.io>
Reviewed-by: Topi Reiniö <topi.reinio@qt.io>
|
| |
|
|
|
| |
Change-Id: Iff846c9f87920989d67858b5ac21f6d0096ce61a
Reviewed-by: Qt Submodule Update Bot <qt_submodule_update_bot@qt-project.org>
|
| |
|
|
|
|
|
|
|
|
|
|
|
|
|
| |
Add lib_pch.h to the list of headers so it is synced by syncqt cpp as
a private header. This doesn't seem right, but it matches what we did
in < Qt 6.4 as well as Qt 5.15.
Without at least one synced private header, the build system code
generates incorrect INTERFACE include directories entries which fail
configuration of user projects when the target in question is linked.
Pick-to: 6.5
Fixes: QTBUG-109423
Change-Id: I11b48954044f057cb66bfc74c34dde5e1ba5739d
Reviewed-by: Jörg Bornemann <joerg.bornemann@qt.io>
|
| |
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
| |
When QDoc encounters a set of overloads in some C++ code, it assigns an
"overload number" to them.
The "overload number" is later used to distinguish the different
overloads, to provide an order and to generate unique linking targets in
the produced documentation.
When QDoc parses the souce code for a C++ source file, it generates a
series of `Node`s, the base class for the internal representation for
documentable elements.
For C++ function/methods, a series of `FunctionNode`s will be generated.
Generally, QDoc collects documentable elements that are related by
other documentable elements in an `Aggregate`, a specific type of `Node`
for documentable elements that are composed by other documetnable
elements.
For example, a C++ class is represented internally as an `Aggregate`,
which is composed of all members of the class itself, such as its
method.
For overload sets, a slightly different approach is performed.
Instead of having the `Aggregate` that represents the container of those
overload sets, such as a namespace or a class, be composed of all the
overloads, the `Aggregate` stores a single reference to one of the
overloads, while the other overloads in the set are referenced through a
chain that starts at the overload that is reference by the `Aggregate`.
That is, if we have a class X, with function Y which has some overloads
Y1, Y2, ..., YN; The `Aggregate` that represents class X will have as
its components only one of the `FunctionNode`s that represent Y1, Y2,
..., YN, say Y1.
The `FunctionNode` that represents Y1 will then have a reference to Y2,
which has a reference to Y3 and so on.
A `FunctionNode` exposes this interface through the
"setNextOverload"/"nextOverload" pair of methods, such that each
`FunctionNode` is part of an implicit linked list that is used when the
element is part of an overload set.
During the parsing of the code, QDoc builds these structures for each
overload set that it finds under elements that it represents as
`Aggregate`s, primarily C++ objects and namespaces.
Later on, before the generation phase, the final step that QDoc performs
during an execution, in which the actual output documentation is
produced and written to disk, all structures of this kind are analyzed
and enhanced.
For each `Aggregate`, its components are considered and, if a component
if part of an overload set, the whole set is modified to associate
"overload numbers" to the elements of the set.
Nonetheless, QDoc was failing in this process, incorrectly not providing
an overload number for a few elements of certain overload sets.
As QDoc uses the "overload numbers" to order the elements of an overload
set in the output documentation, this produces incorrectly ordered
elements in the reference page of, for example, a class.
Furthermore and more importantly, as QDoc uses the "overload numbers" to
produce linking targets for the elements of an overload set in the
output documentation, the lack of of an assigned "overload number" would
result in duplicate anchors pointing to different parts of the same
document.
QDoc performs the analysis of the overload sets starting at
"Aggregate::normalizeOverloads".
The method performs two tasks.
It finds the "primary overload" for the set and it assigns an "overload
number" to each element of that same set.
A "primary overload" is an internal concept that QDoc uses. It
represents the element of an overload set that is the "original"
element, the one that is expected to have the documentation primary
documentation for the whole overload sets.
Internally, the "primary overload" has two characteristic.
- It is the first element of the chain that represents the overload
set the element is a part of
- It has an "overload number" that precedes all other "overload
numbers" in the overload set that the element is a part of
When QDoc parses the source code, it does not have enough information to
know which element is supposed to be the "primary overload". For
example, it doesn't yet know which elements have or don't have a
user-provided documentation.
In turn, this means that it cannot assign "overload numbers" in that
step.
Instead, QDoc produces a temporary chain, that is ordered based on the
order in which the elements of the overload sets are encountered in the
source code, that may or may not contain elements that are incorrectly
ordered in the chain.
`Aggregate::normalizeOverloads`, then, takes care of this temporary chain
by reordering it to assign the required "overload numbers".
Incorrectly ordered elements may be of various kinds. For example, an
element may be marked as an overload by the user through the "\overload"
command but appear as the head of the list due to the ordering of the
source code.
Similarly, an element may be "internal", a special marker that QDoc uses
to identify elements that should not appear in the final generated
documentation.
`Aggregate::normalizeOverloads` takes into account this discrepancies by
re-ordering the chain of an overload set.
First, it finds a suitable member element to be the "primary overload"
and moves it to the top of the chain.
Then, it traverses the chain to assign "overload numbers" and, while
doing so, reorganizes the chain to position "internal" elements
separately, as they will not appear in the output documentation.
`Aggregate::normalizeOverloads` perform the second part of this process
by traversing the chain.
In particular, it would use the obvious method of referencing a node in
the chain and analyze the element that follows it, if any, at each
iteration, while moving
and iteratively move the reference to the next node in the chain
until the chain is exhausted, using a looping construct.
As the last step in the loop, the reference is updated to the next
element of the chain to prepare for the next iteration.
When encountering incorrectly positioned elements of the chain that are
"internal", the elements of the chain would be swapped in place,
to "remove" the "internal" element, moving the next element in the chain
to the place of the "internal" element and, thus, to the next element in the
chain relatively to the one that the iteration was referencing.
When this step is performed, no overload number is assigned for the
iteration.
As with any other iteration, the reference to the chain would then be
updated to the next element in the chain, that is, the element that was
just moved.
As the next iteration of the looping construct analyzes the element that
is the successor of the currently referenced element, it would in
practice skip the analysis of the element that was just moved, thus not
assigning an "overload number" to it.
Visually, for some chain X1 -> X2 -> X3 -> X4 -> ... -> XN, where "^"
marks the element of the chain that is currently referenced at the
start of the loop, "*" marks the element that is analyzed in
that same iteration and "I" marks an "internal" element:
I
X1 -> X2 -> X3 -> X4 -> ... -> XN
^ *
X1 -> X3 -> X4 -> ... -> XN (swap the internal element away)
^ *
X1 -> X3 -> X4 -> ... -> XN
^ *
Thus, elements of an overload set that were preceded in the chain by an
"internal" element, when
`Aggregate::normalizeOverloads` was executed, would not be assigned an
"overload number".
To avoid the issue, the looping construct that performed this process
was modified to reference the next element in the chain at the end of
an iteration only when an "overload number" was assigned, that is, the
chain was not modified, so as to ensure that each element of the chain
was considered during the process.
This change modifies the output documentation that QDoc generates if
such a case of incorrectly numbered overloads were present in it.
All affected elements will be sorted differently than before, following
their place based on their now assigned "overload number".
Furthermore, their linking target will be different, taking into account
the now present "overload number".
Change-Id: I2ee609873f40d284cd7ef36ce786191294f7a291
Reviewed-by: Topi Reiniö <topi.reinio@qt.io>
|
| |
|
|
|
| |
Change-Id: I914ccc09297ac6283d7cf24d5afc96ebdaf294d0
Reviewed-by: Fabian Kosmale <fabian.kosmale@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>
|
| |
|
|
|
| |
Change-Id: I98eec5ef83881f6b5411df348e98b0dc6abf780d
Reviewed-by: Qt Submodule Update Bot <qt_submodule_update_bot@qt-project.org>
|
| |
|
|
|
| |
Change-Id: I668c42938fccd1d3caa5e846e0421703798d315c
Reviewed-by: Qt Submodule Update Bot <qt_submodule_update_bot@qt-project.org>
|
| |
|
|
|
|
|
|
|
| |
We change the type of 'Files' to array of strings. We still allow the
legacy "string with files separated by space".
Pick-to: 6.4
Change-Id: I4bd33906a5c90e4c747443ec40b4e2f6fa72261b
Reviewed-by: Kai Köhne <kai.koehne@qt.io>
|
| |
|
|
|
|
|
| |
Warn if the files listed actually do not exist.
Change-Id: I94557a139401d87eb173cec34fab82c47c8cacd2
Reviewed-by: Jörg Bornemann <joerg.bornemann@qt.io>
|
| |
|
|
|
|
|
|
|
|
|
|
|
|
| |
Tags are specific to each example, so having the "current" list
of tags as a class member for ManifestWriter is misleading. Instead,
adapt the signatures of the helper methods so that tags are explicitly
passed as arguments and return values.
Now that the methods do not access object state anymore, they can also
be static functions.
Pick-to: 6.4
Change-Id: I7edceed18abf24c3c79f6b44d4ac11101ec307ee
Reviewed-by: Luca Di Sera <luca.disera@qt.io>
|
| |
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
| |
QDoc uses a pair of classes, `Sections`/`Section`, to categorize certain
`Aggregate`s, the internal repreentation for documentable elements
composed of multiple documentable elements, to generate a series of
ordered and organized lists in the generated output documentation for
that same `Aggregate`.
For example, it uses those classes to categorize the members of a C++
class so as to build a list of all members of that same class.
A `Section` has a series of internal storages for certain categories of
elements.
For example, it separately stores elements that are
"obsolete"/"deprecated".
Furthermore, it has a series of parameters that are used during the
generation of the output documentation to branch the required style and
processing for the generated elements.
One such parameter is the "status" of the `Section`, set at construction
time, which uses an enumeration, `Section::Status`, with two possible
values, `Obsolete` and `Active`.
Currently, all usages of `Section` always set the "status" to `Active`,
such that the field is redundant.
Internally, no sensible usage of the field or of the enumeration itself
are performed.
The original meaning of the field is unknown. A `Section`, treats
"obsolete" element separately, albeit it always provides storage and
access to the categorization of all elements at the same time,
"obsolete" or not.
Supposedly, it might have originally been
intended to specifically mark `Section` instances that were intended to
deal with "obsolete" members only.
Nonetheless, as the field is unrequired, it is now removed as dead code.
`Section::m_status`, the member storing the status of a `Section` was
removed.
Its getter, `Sections::status`, was removed as a consequence.
Additionally, the only constructor of `Section` was modified to not
require a `Section::Status` argument and to not set `m_status`, as a
consequence of the removal.
Each call of the constructor was updated to remove the usage of the
`Status` argument.
The `Section::Status` enumeration was hence removed, as it generally
lost its purpose.
`Section::insertReimplementedMember`, a method that took care of
dispatching an element that was categorized as reimplemented, e.g an
overridden virtual function, was modified to remove its single usage of
`Section::m_status` and `Section::status`.
The method branched on the condition of `m_status` being `Active`. As
all `Section` used in QDoc have an `Active` status, the condition was
unnecessary and tautological in the current codebase.
A part of the documentation of `Section::insertReimplementedMember` was
removed as it referred to the now removed condition.
A method, `generateSectionList`, present on both the `HtmlGenerator` and
`DocbookGenerator` classes, used to generate a list in the output
documentation based on the contents of a `Section`, took a `Status`
parameter whose only purpose was to decide which storage in `Section` to
use.
That is, the method would consider the "contents" of the `Section` to be
the categorized "obsolete" members if an `Obsolete` status was passed
and all other members otherwise.
The parameter was defaulted so that `Active` was the default choice and
only a single call of the method specified the parameter, passing an
`Obsolete` status.
To allow the removal of `Section::Status`, a temporary change was made to the
interface of the method, so that it uses a `bool` parameter in place of
the original `Status` one.
When the parameter is `false`, its default value, the method behaves as
if an `Active` status was passed, behaving as if `Obsolete` was passed.
Both declaration, definition and usages of the method were updated to
conform to the new interface.
While the usage of a boolean is both more restrictive, extension-wise,
and less clean, all the code related to the `Generator` classes has to
be revised and, almost certainly, changed substantially, such that this
"uglification" of the code is to be considered only temporary, allowing
it to be ignored for the time being while still enabling a
simplification in the too-complex code for `Section`.
Albeit unrelated, the documentation for a now non-existing constructor
of `Section` was removed from "sections.cpp".
Change-Id: Ie234f58f36e99ced40574440d51a9f89ddefb1da
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.
QML elements are structured with relatively more complexity than other
similar maps in `Section`.
Instead of directly using a map, QML `Node`s are destructures into a
lists of pairs, where each pair associates a certain QML `Node` with its
elements, the map itself.
Those are later flattened into a list of similar pairs, where the second
element is a vector of the "values" of the map instead of the map itself.
Supposedly, this is used to support the generation of "all members"
pages for QML elements.
Those pages differ from the one generated for C++ classes as they group
the various members based on the QML element that "generates" them, that
is, inherithed elements are group under the element they are inherited
from, instead of the "elements soup" that the C++ "all members" pages
use.
Hence, the pairs structure simplifies this process, as it preserves a
reference to the generating member and provides the required grouping.
`Section::m_classMapList`, is the list of pairs that is used to hold
all the elements of a destructured `Aggregate` that are QML elements,
and is now removed as it is unnecessary.
Further to removing the member variable, all insertion into the list
were converted to insertion into `Section::m_classNodesList`, the
flattened version of the structure.
Those insertions were performed in two steps and through two methods,
`Section::newClassMap` and `Section::add`.
`Section::newClassMap` was used to create a new pair to add to
`m_classMapList` and is now modified to directly add a pair to
`m_classNodesList`.
`Section::newClassMap` had only a single use, in
`Section::buildStdQmlTypeRefPageSections`, where QML `Aggregate` are
destructured, and was thus removed in favor of moving the construction
of the required pairs inline.
`Section::newClassMap` would create the pairs on the heap and then store
a pointer to them in `m_classMapList`.
There is no currently known reason for this requirement, such that along
with the removal and inlining of `Section::newClassMap` the pairs were
modified to be stored directly.
As the pairs are not on the heap anymore, `ClassNodesList`, the type of
`m_classNodesList` was modified to be a list of `ClassNodes`, a typedef
for the stored pairs, instead of a list of pointers to `ClassNodes`.
The single consumer of `m_classNodesList`,
`HtmlGenerator::generateAllQmlMembersFile`, which generates the actual
"all members" file for QML elements, was modified to take into account
the change in type.
`Section::add` would store a new element in the map of the last added
pair, to populate it, while ensuring that the element was added to the
"all members" category too.
Since it had a single usage, it was removed in favor of an equivalent
inline version.
`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_classMapList` was removed from `Section::clear`, as the
member variable is not part of the internal state anymore.
Furthermore, due to the removal of the heap allocations for the stored
pairs, calls to `qDeleteAll` to free the allocated memory in
`Section::clear` were removed.
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_classNodesList` instead of
`m_classMapList`, as `m_classMapList` is now removed in favor of
`m_classNodesList`.
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 all maps in `m_classMapList` was removed in favor of
sorting all vectors of `m_classNodesList` 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, a previously added comparator that uses
`sortName` as its base was used.
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, s `sortName` produces colliding keys for certain
different elements.
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 QML type, that lists all
elements of the type, inherited or not.
Change-Id: I6ad888af00d83cb3bc6c7a1a852718a7c5e207ad
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 constructing the same monodimensional-structures,
which can be sorted directly, before being presented to a consumer, to
produce the same result.
`Section::m_obsoleteMemberMap`, is one such map that is used to hold all the
elements of a destructured `Aggregate` that are deprecated, 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_obsoleteMembers`, the flattened version
of the map.
`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_obsoleteMemberMap` was removed from
`Section::clear`, as the member variable is not part of the internal
state anymore.
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_obsoleteMemberMap` was removed in favor of sorting
`m_obsoleteMembers` 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, the sorting uses a previously added
comparator that uses `sortName` as its base.
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.
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_obsoleteMembers`, the groups of elements that are produced
from those `SharedCommentNode` will now provide an order.
This only affects, at the current point in time, two output files,
"qkeycombination-obsolete.html" and "qlist-obsolete.html".
Change-Id: Ida4e54c594c6376f2d0ccf8781e8fc07d4a5f49f
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>
|
| |
|
|
|
|
|
|
|
|
|
|
| |
- remove unused variables
- Use QString::arg() with multiple string arguments
- Avoid detaching containers in loops
Pick-to: 6.4
Change-Id: I9b29f5a0269f288b7de862eccdcee9750248dce8
Reviewed-by: Cristian Maureira-Fredes <cristian.maureira-fredes@qt.io>
Reviewed-by: Topi Reiniö <topi.reinio@qt.io>
Reviewed-by: Luca Di Sera <luca.disera@qt.io>
|
| |
|
|
|
|
|
| |
Pick-to: 6.4
Change-Id: Ib68ac437e2583c8f75a18b607548f147cebd3863
Reviewed-by: Topi Reiniö <topi.reinio@qt.io>
Reviewed-by: Luca Di Sera <luca.disera@qt.io>
|
| |
|
|
|
|
|
| |
Pick-to: 6.4
Change-Id: I0d6c597552103251a8c09418d83ea2e38ed10012
Reviewed-by: Topi Reiniö <topi.reinio@qt.io>
Reviewed-by: Luca Di Sera <luca.disera@qt.io>
|
| |
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
| |
As part of producing a documentation set, QDoc generates a series of
lists for certain documentable elements.
For example, it produces a list of all elements that compose a QML type.
Internally, QDoc uses a pair of co-dependent classes `Sections` and
`Sections`.
A `Section` acts as a container for certain `Node`s, the base class of
the internal representation that QDoc uses for documentable elements,
while `Sections` is the public facing interface for all `Section` that
QDoc uses, which are statically determined.
When a `Sections` is constructed, it categorizes the child of an
`Aggregate`, an internal representation for documentable elements that
are composed of multiple documentable elements, so that they can be
consumed to build the lists that QDoc has to generate.
For example, `Sections` is used to categorize the members of a C++
class, such as constructors, destructors, slots and so on, into
organized lists that are then used to produce the reference page of that
same class.
`Sections` and `Section` use a series of internal structures to organize
the elements that should be categorized.
For QML elements, it uses a series of nested structure that are
populated starting at a type.
First, a certain map-like structure is constructed, organizing the
various elements that compose a QML type while sorting them at the same
time based on certain criterias.
Then, the map-like structure is flattened into a similar one-dimensional
nested structure.
At the leaf of this nested structure is `KeysAndNodes`, a pair containing a
list of strings, the keys of the original map-like structure, and a list
of `Node`s, the values of the original map-like structure.
One level up from `KeysAndNodes` there is `ClassKeysNodes`, a pair
joining a `KeysAndNodes` to the internal representation of the "parent"
QML type they are related to, the "Class" in the name of the structure.
QDoc currently has a single usage site that uses this structure,
`HtmlGenerators::generateAllQmlMembersFile`, which produces an output
file listing all elements, inherited or not, that compose a QML type.
While `HtmlGenerators::generateAllQmlMembersFile` makes use of this
structure, it only uses the "Nodes" part of `KyesAndNodes`, making the
"Keys" part dead code.
Hence, `KeysAndNodes` was removed as unnecessary, flattening the
internal structure that `Sections`/`Section` uses by one level, such
that `ClassKeysNodes` is now a pair of that relates the internal
reprensation of a parent QML type directly to its children, with no
"keys" in-between.
`ClassKeysNodes` was renamed to `ClassNodes`, to represent the "lack" of
"keys" that derives from the flattening.
Usages of the type were modified to use the new name.
`Section::classKeysNodesList` was similarly renamed to
`Section::classNodesList`, for consistency, and so its usage sites.
`Section::m_classKeysNodesList`, the internal variable used to hold an
instance of `ClassKeysNodes` was renamed, similarly, to `m_classNodesList`.
Change-Id: I11697afb46544a3f9f925a5d239124093bbc46df
Reviewed-by: Topi Reiniö <topi.reinio@qt.io>
|
| |
|
|
|
|
|
|
|
| |
The group got renamed to cmake-commands-qtlinguisttools in commit
5566a6d923.
Pick-to: 6.2 6.4
Change-Id: I85f6416cbb7b41650f9eaf38aa274eacb05cf884
Reviewed-by: Jörg Bornemann <joerg.bornemann@qt.io>
|
| |
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
| |
`HtmlGenerator::generateAllQmlMembersFile`, the method that produces the
output documentation for the page that lists all documentable elements
that compose a QML type, produces its output by destructuring a certain
structure containing an internal representation of the elements that
will be listed in the produced file.
The structure, which is constructed and provided by `Sections`, an
internal structure that categorizes `Node`s, the base class for the
internal representation that QDoc uses for documentable elements, such
that they are usable to produces certain list of elements, provides the
required elements as a complex nested structure, the leaf part of which
is a pair of "keys" and "values".
When destructuring this complex structure, the method would access the
leaf part of the structure and use both the "keys" and "values" that
composed it.
The "values", which are `Node`s representing the elements of the list to
be produced, are iterated over to produce the output documentation.
The "keys", were used to bound the iteration over the "values", that is,
their size was used as the bounding condition for an arithmetic loop
iterating over the "values".
As the "values" themselves are stored into a vector, their is no need to
use the "keys" to bind the loop, as the size of the "values" vector
itself is sufficient, and more correct, to provide the same binding.
Hence, the usage of "keys" to bind the loop that iterated over the
"values" was removed, as unnecessary.
No behavior change should be produced as a consequence.
Since the "keys" and the "values", which are produced from the keys and
values of an internal `MultiMap` used by `Sections` to produce the above
mentioned "keys" and "values", are expected to generally be the same
size, unless collision were encountered when building the `MultiMap`, in
which case the usage of the "keys"' size would not correctly iterate
over the whole of "values", producing an incomplete documentation.
No such case seems to be present in the current Qt documentation, such
this change is not expected to modify the final state of the output documentation.
Change-Id: I61ce73aa504bdc996abf657c15f399945a44fbc4
Reviewed-by: Topi Reiniö <topi.reinio@qt.io>
|
| |
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
| |
`HtmlGenerator::generateAllQmlMembersFile` would loop a vector
structure to generate the list of members for a Qml type.
The structure was traversed trough a loop bound on the size of the
structure, such that if the structure is empty no iteration would be
performed.
Nonetheless, an additional scope wrapped the loop block, avoid the
execution when the structure was empty, that is, when its size was 0.
The unnecessary additional block and indentation further cluttered the
code and was thus removed with no change in behavior.
Change-Id: I910cb13dfa2a1b91e7701e1c78c7f1808ed0f1b5
Reviewed-by: Topi Reiniö <topi.reinio@qt.io>
|
| |
|
|
|
| |
Change-Id: I8c746668f4665ff72272b01c86ca1f6fd098bff2
Reviewed-by: Qt Submodule Update Bot <qt_submodule_update_bot@qt-project.org>
|
| |
|
|
|
|
|
|
|
|
|
|
| |
- 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>
|
| |
|
|
|
| |
Change-Id: I17aff5d46cd3e63442c8a4ff0cb8b72f981833df
Reviewed-by: Qt Submodule Update Bot <qt_submodule_update_bot@qt-project.org>
|
| |
|
|
|
|
|
|
|
|
|
| |
qdoc often retrieves the contents of a source file and matching
headers via the clang cursors when parsing. Cache the last files
except the dummy file to avoid reading the same file many times. This
avoids roughly 43000 file reads in qtbase.
Pick-to: 6.4 6.2
Change-Id: I33fcc57039acfc667e095e782cdd6eb4f592028b
Reviewed-by: Luca Di Sera <luca.disera@qt.io>
|
| |
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
| |
QDoc uses a pair of classes, `Section`/`Sections`, when generating the
final documentation, to organize and classify the known documentable
elements into categories that are later used to generate certain ordered
lists of items, such as the list of members that a C++ class has.
Internally, `Sections` dispatches an `Aggregate`, the internal
representation used for documentable elements that are composed of
multiple documentable elements, and its children into a series of
`Section` to categorize them.
Multiple methods are implemented to perform this dispatch, based on the
"kind" of aggregate that is being dispatched.
When `Sections` dispatches representations for C++ classes, structs of
unions, it performs the initial dispatch of the `Aggregate` through
`Sections::buildStdCppClassRefPageSections`, whose categorization is
later used, generally, during the generation of the lists in the
reference page of that same C++ element in the output documentation.
`Sections::buildStdCppClassRefPageSections` iterates, between other
things, the documentable elements that compose the `Aggregate`, and
their children if any, to categorize them.
A flag variable, `documentAll`, would branch the code based on the main
`Aggregate` that was being categorized.
When `documentAll` was false, any element that did not have a
user-provided documentation would be left out, thus not appearing in the
lists that would be generated by through the `Sections`.
When `documentAll` was true, this filter would be bypassed, generally
document all elements and their children independently of the presence
of any user-generated documentation.
`documentAll` always defaulted to true. It then was considered false if
and only if the dispatched `Aggregate` had a parent but didn't have a
name or a documentation.
It is expected by QDoc, but not enforced, that all `Aggregate`s have a
name, such that no `Aggregate` can trigger, unless a bug is present, the
condition to make `documentAll` false.
The only exception to this is the "root namespace", a "special"
`Aggregate` that sits at the top of the internal tree-representation of
documentable elements built by QDoc.
Nonetheless, the "root namespace" does not have a parent, such that it
couldn't trigger the condition either.
Furthermore, the "root namespace" has a "namespace" "kind", and is thus
dispatched to a different method, `Sections::buildStdRefPageSections`,
such that it would not pass by the same `documentAll` condition at all.
Hence, it should be theoretically impossible for the condition to
trigger, making the `documentAll` flag and branching superfluous, as it
is always expected to be true.
Hence, `documentAll` and its related branching was removed from
`Sections::buildStdCppClassRefPageSections` as dead code, to simplify
the method and remove part of its cruft.
The original reason for the presence of `documentAll` is unknown.
It is supposed that there was originally no distinction between methods
for the dispatch of differently-kinded `Aggregates`, such that the
condition was supposed to specifically trigger for certain elements and
lost its purpose during a refactoring of `Sections`/`Section`.
Nonetheless, no internal representation of the recent and less
recent times is known to sensibly be identified by the presented
condition, such that the condition might have been incorrectly
transcribed, might have never been correct to begin with or might have
depended upon certain bugs or behavior that have faded with time.
As the original reasoning for the condition is uncertain, it is possible
that certain now unknown bugs might resurface in the future, such that a
certain eye to unexpected changes in the output documentation should be
kept in the short-term.
This patch has no visible effect on the current the current
documentation output.
Change-Id: Iaefa5c04aa1bdf4e46f7f50cce03033f024d7ce8
Reviewed-by: Topi Reiniö <topi.reinio@qt.io>
|
| |
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
| |
libclang from LLVM version 15 causes a lot of parsing failures with
the 'error code: 4' specifically when initialized with C++20 support.
This problem is highly likely to be fixed in LLVM 16 release.
Drop down to C++17 standard if libclang from LLVM 15 is detected.
There are a few places in the Qt API where certain features are
conditionally enabled for C++20 in a way that's also visible in
the generated documentation. These can be worked around separately.
Pick-to: 6.4
Fixes: QTBUG-94365
Change-Id: I5a3fd14dfe07102595fc941b27c46688b0f29697
Reviewed-by: Luca Di Sera <luca.disera@qt.io>
|
| |
|
|
|
|
|
|
|
|
| |
Since the switch to clang, qdoc cannot process wildcard
based defines anymore. Update documentation accordingly.
Pick-to: 6.4
Change-Id: I3e1bf3234e17bcd46cbb4c2bd72ea33ad188fc9c
Reviewed-by: Luca Di Sera <luca.disera@qt.io>
Reviewed-by: Topi Reiniö <topi.reinio@qt.io>
|
| |
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
| |
When QDoc generates the page for a C++ class, it generates a summary
list of the direct (non-inherited) members of that class (methods,
slots, ...) and a detailed list of those same members.
Furthermore, it generates an additional page that lists all members,
inherited or not, for that class.
Elements of those variouso lists are ordered under a certain
methodology.
For example, currently, QDoc orders the constructors at the top, before
other specially-ordered members.
Internally, QDoc has some special handling for copy/move constructors.
Indeed, a `FunctionNode`, the internal representation that QDoc uses for
C++ functions, has a "metaness" attribute that will be set depending on
the kind of element the `FunctionNode` represents, with special cases
for copy and move constructors.
Currently, QDoc orders all constructors "at the same levels",
independently of the kind of constructors they may be.
Due to an implementation detail, this will usually, but not necessarily
always, mean that the constructors will appear in the order they were
declared in the code.
That is, if some class X has constructors X1, X2, X3, and they are
declared in whatever header file in the order X1, X2, X3, they will be
ordered as X1, X2, X3 in the relevant generated lists.
If the same constructors where declared with order X2, X1, X3, in
whatever header file, they will be ordered as X2, X1, X3 in the relevant
generated lists.
The major implementation detail that provide this ordering, an internal
number that is assigned to overloads, is independent of the ordering
algorithm that QDoc uses.
Furthermore, the ordering that QDoc uses is not total, such that
distinct elements may not be uniquely orderable.
Those two properties together ties some of the ordering to the internal
implementation that the ordering routine uses, with the issue that
changing the implementation might change the ordering itself.
In particular, the current implementation is provided by the
free-function `sortName` in "sections.cpp", that is used by the
`Section`/`Sections` pair of classes to provide an ordered view of
certain lists that QDoc generates.
Internally, the result of a call to `sortName`, is used as the key in
one or more multimaps that later provide the required ordering, which is
implementation dependent when collisions are met.
A certain case where collision might happen has been between copy/move
constructors and other constructors, generally the default one, where
the same `sortName` is produced.
The collision behavior for those constructors might actually stem from a
different bug in the codebase that has not yet been investigated and
might later be addressed.
It is expected that the internal implementation that provides the
sorting might be changed in the near future and then changed again at a
later phase, such that those implementation dependent ordering might
modify the current look of the documentation.
To avoid the issue of the ordering changing between implementations,
`sortName` now guarantees that the result that is produced for each of a
constructor/copy constructor/move constructor is distinct from the one
produced for the other two kinds.
`sortName` uses prefix letters prefix letters prepended to the name of a
certain element to provide the main sorting. To implement the new
behavior, different prefix letters will now be applied to different kind
of constructors.
In particular, a "D" for a copy constructor, an "E" for a move
constructor and a "C" for each other constructor.
Due to the addition of new elements, to preserve the original ordering,
the prefix letter for other elements has now been changed. For example,
a destructor would previously have a prefix letter of "D" while now it
would have a prefix letter of "F".
The provided ordering now ensures that all non-copy, non-move
constructors will be listed, later followed by copy constructors and
finally followed by move constructors.
The ordering of non-constructor elements is unchanged.
A small chunk of code in `sortName`, dealing the ordering of classes,
was moved up in the function.
This result in no semantical changes but is expected to simplify the
top-down reading of the function, as it more closely mimics the final
ordering of the elements in the generated lists.
This change impacts the current documentation by moving around the
order of some copy/move constructors which were previously interleaved
with other constructors. The content of the documentation is not
expected to be touched by this change.
Change-Id: I1ee3e63d971644fbcd0b20a8ed1f55dcb0b30655
Reviewed-by: Topi Reiniö <topi.reinio@qt.io>
|
| |
|
|
|
|
|
|
|
|
|
|
|
|
| |
A browser translates everything by default, which means
even the <code>, <pre>, <table>s listing the class members,
and so on, are also translated. With this change, such HTML
blocks will include the "translate=no" attribute, indicating
that they should not be translated.
Pick-to: 6.4 6.2 5.15
Fixes: QTBUG-106679
Done-with: Topi Reinio <topi.reinio@qt.io>
Change-Id: I446fe26c73b9e3fee2984297bd504ae72c555e73
Reviewed-by: Topi Reiniö <topi.reinio@qt.io>
|
| |
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
| |
QDoc represents documentable elements extracted from source code as
elements of the `Node` class and its derivatives.
In particular, it represents C++ function, methods and so on as
inhabitants of `FunctionNode`.
`FunctionNode` stores a simplified view of the properties of such an
element that are later used by QDoc to perform some sanity checks and to
actually generate the documentation for the element.
One such property, the "metaness", indicates what kind of element the
inhabitant of a `FunctionNode` might actually represent.
The "metaness" is generally set to identify some special cases that
later branch the execution of code and command the way in which the
documentation for the element is generated.
For example, due to the desire to sort the methods of a C++ class when
QDoc is listing its element, a special metaness is assigned to, for
example, constructors, move-constructors and copy-constructors.
The "metaness" of a `FunctionNode`, together with some of its other
properties, is generally set by QDoc while parsing the various source
files through `ClangCodeParser` and, specifically, in
`ClangCodeParser::processFunction`, where an instance of a
`FunctionNode` is populated by its equivalent code-level libclang
`CxCursor`.
The condition that would identify whether a `FunctionNode` should have a
metaness representing a copy-constructor was bugged since its
introduction.
In particular, the current implementation considers the spelling of the
type of the parameters of a method, if it is a constructor, and marks it
as a copy-constructor when a parameter that is a reference is spelled
exactly the same as the parent class of the method.
That is, when a constructor "X" of class "X" has a parameter "X&".
This specific implementation that used the spelling, failed to identify
the very general usage of const-references in a copy constructor.
When the type of a parameter is qualified, such as with "const",
libclang will consider that qualifier in its spelling unless removed,
for which there is no direct method in pre-16 libclang.
The implementation would remove the reference part, "&" or "&&", through
`clang_getPointeeType`, which is further incorrect as it would work for
pointer types too, but would not address any of the possible qualifiers
in the spelling.
Then, it would directly check the spelling to the name of the
constructor, that is, the name of the containing class.
Not addressing the qualifiers would thus fail for reference types that
were qualified. For example, a constructor "X" with an argument of type
"const X&" would be spelled by libclang as "const X" but would be
compared by the implementation to "X", thus always failing.
This was particularly visible for copy-constructors, as the most common
way to implement a copy-constructor is with a unary-constructor whose
argument is of type "const X&".
Indeed, in the years since this code was implemented, QDoc never
actually identified the "metaness" of copy-constructor correctly,
albeit, fortunately, with little impact on the produced documentation.
To avoid the issue, qualifiers are now handled in
"ClangCodeParser::processFunction" when identifying the metaness of a
constructor.
While this solves the issue at hand, "ClangCodeParser::processFunction"
is still bugged with regards to its intention in multiple ways, such as
considering all arguments for the "metaness" checks or not correctly
handling the non-common cases of copy/move-assignment-operators.
An annotation was added to the code to handle the issue when LLVM16,
where a series of patches that we pushed upstream will be available,
will be out, as it will allow us to greatly simplify the code and
correct the bugs as the same time.
The remaining bugs are not expected to be corrected at the current time
due to the unnecessary complexity of the required handling due to the
current limitation in libclang's AST.
The bug are considered safe to preserves for a limited amount of time as
they do not generally impact the way in which the Qt Project writes the
relevant code-elements, and are only dangerous when some specific cases
would otherwise be encountered.
The output documentation will not currently be affected by this change,
albeit the produced "index" files, an intermediate representation of the
code that QDoc produces that is generally consumed both by QDoc and
externel consumers, will incur modifications due to the corrected
identifying of the copy-constructors.
Change-Id: I59ec2c897106a34300b91a175664c0ba07d28f5c
Reviewed-by: Topi Reiniö <topi.reinio@qt.io>
|
| |
|
|
|
| |
Change-Id: If940ce41823f5949235ee176c26e36cc26a593f0
Reviewed-by: Qt Submodule Update Bot <qt_submodule_update_bot@qt-project.org>
|
| |
|
|
|
|
|
|
| |
In "silent log mode" one validation check was dysfunctional.
Pick-to: 6.4
Change-Id: Ia062b7096f00e1d1289ad748a221e99054412109
Reviewed-by: Kai Köhne <kai.koehne@qt.io>
|
| |
|
|
|
| |
Change-Id: I1ededbfda0b397bc669c2ada73111666e499c799
Reviewed-by: Qt Submodule Update Bot <qt_submodule_update_bot@qt-project.org>
|
| |
|
|
|
|
|
|
|
|
|
| |
In line with the recent change in QLocale's nomenclature, do the same
in Linguist. In the process, obtain a list of territory enum values
sorted by territory name a little more efficiently, bypassing an
intermediary unsorted list of territory enum values.
Change-Id: I18fed74499312f0b502bc8a93fbb2a69c65bca05
Reviewed-by: hjk <hjk@qt.io>
Reviewed-by: Qt CI Bot <qt_ci_bot@qt-project.org>
|
| |
|
|
|
|
|
|
|
|
| |
Separator actions are generated using QMenu::addSeparator();
they are not designable.
Fixes: QTBUG-108243
Pick-to: 6.4
Change-Id: I0c2141f9703e84cedda72038fcc070386ad00565
Reviewed-by: Jarek Kobus <jaroslaw.kobus@qt.io>
|
| |
|
|
|
| |
Change-Id: Ic08f1d0cfadfafe61a558d9bde16136778fb555e
Reviewed-by: Topi Reiniö <topi.reinio@qt.io>
|
| |
|
|
|
|
|
|
|
|
|
| |
Provide a landing page for LinguistTools macros, making it easier
to navigate between them in the breadcrumb menu. Also add details on
where the respective command is found.
Task-number: QTBUG-96239
Pick-to: 6.2 6.4
Change-Id: Ib74c6cab2215900e1b43ea26fce293ea74d154f0
Reviewed-by: Jörg Bornemann <joerg.bornemann@qt.io>
|
| |
|
|
|
|
|
|
|
| |
The parts of raw HTML tables (RawString atom) are intertwined with
cooked strings (String atom).
Change-Id: I918b789939462e2eafb6a312d658cacae70f90f8
Reviewed-by: Paul Wicking <paul.wicking@qt.io>
Reviewed-by: Topi Reiniö <topi.reinio@qt.io>
|
| |
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
| |
In certain situations depending on the build environment and
the libclang version that QDoc links against, Clang may be
unable to resolve the correct system include paths
automatically. This seems to be the case particularly for the
portable QDoc binary that is provisioned into test builds
in the CI system, and results in spurious documentation
warnings.
Query the paths from GNU C++ compiler on Linux, just like
we already do for macOS/clang++.
Pick-to: 6.4
Task-number: QTBUG-108353
Change-Id: I92ffb4da0ce8af166084eb20a29ec4b00c047489
Reviewed-by: Luca Di Sera <luca.disera@qt.io>
Reviewed-by: Kai Köhne <kai.koehne@qt.io>
|
| |
|
|
|
|
|
|
|
|
|
|
| |
This reverts commit 1efd6fe7403fe6873c81a0f418112fc205a76cb5.
Reason for revert: This patch removed the QML.<type> identifier, which
is used by Qt Creator so far.
Pick-to: 6.4 6.2
Change-Id: If96ac1b773a6191c214db4e75c74d5f23bc69c92
Reviewed-by: Paul Wicking <paul.wicking@qt.io>
Reviewed-by: Topi Reiniö <topi.reinio@qt.io>
|
| |
|
|
|
| |
Change-Id: I2480ea811fa90ed4544f2d05e22c2d5b4bcd1a2d
Reviewed-by: Qt Submodule Update Bot <qt_submodule_update_bot@qt-project.org>
|
| |
|
|
|
|
|
|
| |
Amends commit 59a6e371b
Pick-to: 6.4
Change-Id: Ib73cd9fd3d569f79c546814c9d5dd3d2b296e035
Reviewed-by: Topi Reiniö <topi.reinio@qt.io>
|
| |
|
|
|
|
|
|
|
| |
Do not explicitly mention OpenGL acceleration anymore. Qt Quick
nowadays can use different backends for accelerated graphics.
Pick-to: 6.4
Change-Id: Ice4dc20db6db7a9032e16c62e035a64f7b17c409
Reviewed-by: Paul Wicking <paul.wicking@qt.io>
|
| |
|
|
|
|
| |
Pick-to: 6.4 6.3 6.2
Change-Id: Ie6caa2f8ec7f55db137010df775b6c44d4f0d2e5
Reviewed-by: Leena Miettinen <riitta-leena.miettinen@qt.io>
|
| |
|
|
|
|
|
|
|
|
| |
Bring the alphabet table of contents back.
Refactor the DocBook output to be more consistent with the DocBook
grammar (a varlistentry only has one listitem: still output one entry
per letter/digit, but with a list within).
Change-Id: I8a9d0d77f73563fb5e064d20d781dc1ee79db012
Reviewed-by: Paul Wicking <paul.wicking@qt.io>
|
