| Commit message (Collapse) | Author | Age | Files | Lines |
|---|
| |
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
| |
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>
|
| |
|
|
|
|
|
|
|
|
|
|
|
|
|
| |
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>
|
| |
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
| |
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>
|
| |
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
| |
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>
|
| |
|
|
|
|
|
|
|
|
| |
Since dropping support for QDoc's alias configuration
variable, DocParser::terminate() is a noop. Drop the
method.
Task-number: QTBUG-111670
Change-Id: Ic9f1e44d3d87a7c13353dc2538735003febf6484
Reviewed-by: Topi Reiniö <topi.reinio@qt.io>
|
| |
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
| |
For "compatibility reasons", support for renaming commands through an
"alias" defined in a .qdocconf-file was introduced to QDoc. In
particular, this was an aid when renaming QDoc's \input command to
\include. This usage has since been unified in Qt, with the exception
of in QDoc's own documentation project, and the more powerful \macro
command can be exercised to achieve the same behavior.
This feature's implementation obstructs efforts to make QDoc's code more
thread safe. As there are no known usecases, remove support for renaming
commands to pave the way for a more performant QDoc.
[ChangeLog][QDoc] Support for the 'alias' variable in qdocconf-files is
removed. Use QDoc's 'macro' construct instead.
Fixes: QTBUG-111670
Change-Id: Ifcf8a47ee1e1940607cec4841e6ba06b493e6d24
Reviewed-by: Topi Reiniö <topi.reinio@qt.io>
|
| |
|
|
|
|
|
|
|
|
|
|
|
| |
* Use qsizetype instead of int.
* Remove unnecessary variable 'startLine'.
* Replace a while loop with a for loop.
* Replace nested conditional statements with (A && B).
* Fix a corner case where a lone snippet tag at the last line of
included file caused out-of-bounds access of the line buffer.
Pick-to: 6.5 6.4 6.2
Change-Id: I0b1009cf122681bcf700b67040a3d0ca19e82378
Reviewed-by: Paul Wicking <paul.wicking@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>
|
| |
|
|
|
|
|
|
|
|
|
|
|
|
|
| |
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>
|
| |
|
|
|
|
|
|
|
|
|
|
| |
- 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>
|
| |
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
| |
QDoc supports multiple versions of macros, one for each supported output
format:
macro.hello.HTML = "<p>Hi, \1</p>"
macro.hello.DocBook = "<db:para>Hi, \1</db:para>"
Macros can also take arguments. However, with multiple format-specific
versions defined, QDoc attempted to also read the arguments multiple
times. This fails on the second attempt as the internal position has
been already advanced beyond the arguments.
Implement a new helper function, DocParser::getMacroArguments(), and
use it to read the arguments only once.
Fixes: QTBUG-108219
Pick-to: 6.2 6.4
Change-Id: Icad7e51b93c00a2632746ea2fe05d36459b9acda
Reviewed-by: Paul Wicking <paul.wicking@qt.io>
|
| |
|
|
|
| |
Change-Id: Ie224dc3e3387cd04369aeb96e3cb14ec3447bbc4
Reviewed-by: Paul Wicking <paul.wicking@qt.io>
|
| |
|
|
|
|
|
|
|
|
|
|
|
|
|
| |
We've been requiring C++17 since Qt 6.0, and our qAsConst use finally
starts to bother us (QTBUG-99313), so time to port away from it
now.
Since qAsConst has exactly the same semantics as std::as_const (down
to rvalue treatment, constexpr'ness and noexcept'ness), there's really
nothing more to it than a global search-and-replace.
Task-number: QTBUG-99313
Change-Id: I234704ba429750ddee958a82f6c941d041da0653
Reviewed-by: Jarek Kobus <jaroslaw.kobus@qt.io>
Reviewed-by: Ivan Solovev <ivan.solovev@qt.io>
|
| |
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
| |
This is a semantic patch using ClangTidyTransformator as in
qtbase/df9d882d41b741fef7c5beeddb0abe9d904443d8:
auto QtContainerClass = anyOf(
expr(hasType(cxxRecordDecl(isSameOrDerivedFrom(hasAnyName(classes))))).bind(o),
expr(hasType(namedDecl(hasAnyName(<classes>)))).bind(o));
makeRule(cxxMemberCallExpr(on(QtContainerClass),
callee(cxxMethodDecl(hasAnyName({"count", "length"),
parameterCountIs(0))))),
changeTo(cat(access(o, cat("size"), "()"))),
cat("use 'size()' instead of 'count()/length()'"))
a.k.a qt-port-to-std-compatible-api with config Scope: 'Container',
with the extended set of container classes recognized.
Change-Id: I95f6410e57a6a92b1cf91bbedfbe3d517cab6b44
Reviewed-by: Qt CI Bot <qt_ci_bot@qt-project.org>
Reviewed-by: Kai Koehne <kai.koehne@qt.io>
Reviewed-by: Friedemann Kleint <Friedemann.Kleint@qt.io>
|
| |
|
|
|
|
|
|
|
|
|
|
|
|
|
| |
The pair was deprecated in eb99338568dab0bd62144e1009974d5317b53037 and
was marked as to be removed in Qt 6.4.
As the release of 6.4 is near, we now remove all remaining code related
to the two commands.
[ChangeLog][qdoc] The deprecated \oldcode, \newcode commands were removed.
Fixes: QTBUG-98500
Pick-to: 6.4
Change-Id: I06525d15836f07abca5ddfebe9eb557e9e9909a0
Reviewed-by: Kai Koehne <kai.koehne@qt.io>
|
| |
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
| |
QDoc provides an undocumented, not-officially-support, command pair,
"\js"/"\endjs", that allows a writer to include a codeblock of
javascript code in the documentation.
This is part of a suite of commands to allow pure javascript support
that was never finalized and is now being removed from the codebase.
Hence, all code related to the command pair is now removed and support
for it is dropped.
Some of the input data in the regression suite was modified as it made
use of a single instance of the command pair.
The regression files were regenerated to take into account the removal.
Fixes: QTBUG-106275
Change-Id: I1e18009617884a3841b0e2b83d4f5e34c7e14971
Reviewed-by: Topi Reiniö <topi.reinio@qt.io>
|
| |
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
| |
The codebase for QDoc has support for commands related to documenting
pure javascript codebases.
Generally, given a certain QML specific command, a javascript equivalent
is provided.
For example, "\jstype" or "\jsmodule".
Codewise, the support is bolted on by reusing the exact same code that
is used for QML types. The internal structures used to represent QML
elements, like `QmlPropertyNode`, were reused for javascript elements,
with the sole difference of changing the metaness value, for elements
where the metaness is meaningful, and the internal type tag of the node.
Code that branched specifically with QML types was modified to branch
for javascript types too, with mostly no other difference in the
branched code itself.
The support for javascript was never finalized, albeit it is supposed to
work, lacking, for example, representation in the documentation.
As a consequence of this it is not currently used, tested or necessary.
Hence, the code supporting the documentation of javascript elements is
now removed as dead code.
Anything referring to javascript specific elements were removed, from
the commands definitions to the categorization functions.
"Node::changeType" and "FunctionNode::changeMetaness", that switched the
type and metaness, respectively, of an existing node with a new one,
albeit implemented in a more general fashion, are now removed as dead
code, since they were used specifically to "convert" Qml nodes to
"javascript nodes".
References to javascript were removed in the documentation for QDoc.
Do note that not all javascript related features were removed from the
codebase.
In particular, the "js" and "endjs" commands, to mark a codeblock as
being javascript code, and their supporting code such as `JsCodeMarker`,
were currently retained as, albeit no documentation exists, are
currently used a couple of time in the current Qt's codebase.
The remaining javascript specific code is expected to be addressed and
removed in a future commit, unless the current usages are specific
enough that they cannot be replaced with qml specific commands.
Task-number: QTBUG-106275
Change-Id: I6a199ce97b26d6a3a645c0022e599a8654989a85
Reviewed-by: Topi Reiniö <topi.reinio@qt.io>
|
| |
|
|
|
|
|
|
| |
That is required to propagate deprecation warnings to internal tools
Task-number: QTBUG-105102
Change-Id: Ibb60b75653bdd482ba505685bd8a589ffffa8786
Reviewed-by: Sona Kurazyan <sona.kurazyan@qt.io>
|
| |
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
| |
This patch modifies the DocParser such that QDoc will now treat two
consecutive hyphen characters (--) as markup that outputs an en dash
character, and three hyphens (---) as markup for an em dash.
As the rules governing use of en dashes and em dashes are defined by
style guides and not grammar, QDoc is left generally permissive of
their use. However, code blocks and content that is monospaced (passed
to the \c-command), must be left untouched, as otherwise, errors,
such as the mangling of the decrement operator in code snippets, could
occur.
Also ensure that the HTML QDoc generates uses the correct HTML entity
codes.
Of course, not feature of QDoc is complete without documentation.
Even though it strictly speaking isn't a command, due to the
organization of content in the QDoc manual, add documentation for en
dash and em dash sequences to the markup command section.
[ChangeLog][QDoc][QDoc now interprets -- as en dash, and --- as em dash.]
Fixes: QTBUG-105729
Change-Id: I2b6d547dcd9d8b4f1d9348f2596c7b0abc28d039
Reviewed-by: Luca Di Sera <luca.disera@qt.io>
Reviewed-by: Topi Reiniö <topi.reinio@qt.io>
|
| |
|
|
|
|
|
|
| |
Some cases that break with Qt's coding conventions
have slipped through code review, fix them.
Change-Id: I758217fed00ac60ea4c78a40ba1fa4fb9feb8ace
Reviewed-by: Topi Reiniö <topi.reinio@qt.io>
|
| |
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
| |
The \code command is used widely to document also QML code snippets,
however, QDoc failed to detect the code as QML because the default
code marker is the CppCodeMarker. The consequence was that QDoc
failed to detect and auto-link to QML types in code snippets.
The default marker to use depends on the 'language' configuration
variable and pure QML documentation projects can set it to QML
instead. Many projects consist of both C++ and QML module docs
however, and using a single project-wide setting is less than
optimal.
As a compromise, use the QML marker for \code snippets appearing
within QML-specific topics as the default code marker. Ensure
that the code is detected as QML - this prevents unexpected
warnings for parsing failures typically seen with the \qml
command.
Note that the downside of the chosen solution is that QML topic
command must appear before the \code commands for the automatic
marker selection to take place. This can't be helped as all
commands are parsed sequentially and we don't know the topic
beforehand. Typically this is not a problem as the convention is
to start the documentation comment with a topic command, even
though QDoc doesn't strictly require it.
Task-number: QTBUG-103791
Change-Id: I87f2549c7c258a15fc02f64f65ef7fa0b28b5a68
Reviewed-by: Topi Reiniö <topi.reinio@qt.io>
|
| |
|
|
|
|
|
|
|
|
|
| |
Replace the current license disclaimer in files by
a SPDX-License-Identifier.
Files that have to be modified by hand are modified.
License files are organized under LICENSES directory.
Task-number: QTBUG-67283
Change-Id: I5335388c0472b0ee554234fc7eca60769e504660
Reviewed-by: Jörg Bornemann <joerg.bornemann@qt.io>
|
| |
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
| |
The recently added `FileResolver` abstraction encapsulate the logic that
QDoc uses for finding user-provided files in the documentation that QDoc
will need to interface with.
Previously, this process was mostly contained in `Doc::resolve_file`.
This was considered problematic as `Doc` is an extremely complex class
with many responsibilities, coupling the logic with many unrequired
preconditions and making testing of this simple logic almost
unattainable.
Furthermore, a similar logic in QDoc was provided by `Config::findFile`,
which was sometimes used instead of `Doc::resolveFile`, fracturing the
behavior of the code.
To avoid those issues, allow for the testing of the logic for file
resolution and to generally simplify the code and make it more
consistent, `Doc::resolveFile` was removed and substituted with the
`FileResolver` abstraction.
A few changes were made to support this new idiom.
- An instance of `FileResolver` is now built in `processQdocconfFile`
and passed as a reference to systems that require it during
construction.
A small exception was made for `DocParser` where the instance is passed
as a pointer through `DocParser::initialize` to support the current code
structure.
The required changes to the relevant entities constructors were made to
allow for this.
- `FileResolver` is provided as an explicit dependency to anything that
requires the capability of resolving files, such as generators.
Generally during construction.
This is intended as a first step in removing the intitialize-terminate
idiom, reducing the scope of some of the mutable state and increasing
the expliciteness of its provenance.
To allow for this, the main routing of QDoc was modified to construct
the Generators classes during the production of the documentation in
`processQdocconfFile`.
This was required as an initialized `FileResolver` is needed for the
generators to work. As `FileResolver` instead depends on a parsed
configuration, it was not possible anymore to construct the generator
once before doing anything else.
A small defensive addition to `Generator::terminate` was added, removing all
generators from the list of generators. This should not actually be
required, but it was added to ensure that the now more limited scope of
the generators and the possibility that they would be constructed more
than once would not collide with their broader, unrequired global scope.
- To take into account the simplified data requirements for
`FileResolver`, compared to the previous logic, such the usage of a
single list of directories, the extraction of relevant values from the
configuration in `processQdocconfFile` was modified to further mold the
data into a suitable format for `FileResolver`.
- As the data is relevant to searching directories is contained within
the `FileResolver` instance that underlying systems use and does not
require any processing to be retrieved, some of the caching members in,
for example, `Generator` that contained a reference to this data were
removed.
See, for example, `Generator::s_exampleDirs`.
As a consequence of all those changes, `Generator::augmentImageDirs` and
`Generator::setImageFileExtensions` were removed as unused.
- `Generator::generateExampleFilePage`, was modified from having two
overload to a single method with a default argument to reduce the bloat.
- `Generator::addImageToCopy` was modified to use a `ResolvedFile`.
The method copies an image from the examples to the output directory.
This should be done only when the image is available.
- Places where `Doc::resolveFile` were called were modified to use
`FileResolver::resolve`.
Due to this change some underlying methods were modified to require a
`ResolvedFile`.
`Doc::resolveFile` was removed as a consequence.
- `Doc::quoteFromFile`, which previously depended on `Doc::ResolveFile`,
was modified to require a `ResolvedFile`.
This lightens the responsibility of the method to quoting only, instead
of finding the file and quoting, ensuring that it is called only when
the quoting can actually happen. Furthermore, it removes the need for
some of the error reporting which is bubbled up to the caller during
file resolution.
This was further required to avoid having `Doc` require a `FileResolver`
instance, as `Doc`'s constructor is called in many places.
- The usage of a `userFriendlyFilePath` was removed from code using
`Config::findFile`.
A run of QDoc on the current documentation shows that
`userFrinedlyFilePath` is always equal to the original path that was
passed to find file except in two cases where `userFriendlyFilePath`
would be null.
Consumer code didn't seem to make any use of the null state of the
`userFriendlyFilePath` and ignoring it doesn't seem to change the output
documentation, such that it was considered safe to avoid.
It is currently unclear what the original purpose of this element was.
As `Doc::resolveFile` implicitly used `Config::findFile` and exposed
back the `userFriendlyFilePath`, this is true for all replaced usages of
the method too, which allowed ignoring the element in the first place.
- A now unused overload of `Config::findFile` taking a series of
extensions for the searched for file was removed.
- `Config::copyFile` was modified to remove some of the processing done
to its input parameters which is now unused.
A simplified version of it was retained to handle a known case that is
actually used by the code.
- `DocParser` was modified to internally make use of `FileResolver` for
when resolving files for quoting and some code handling.
It previously used a mix of `Doc::quoteFromFile` and its internal
`quoteFromFile`.
The usages were made consistent depending only on the internal
`quoteFromFile`.
`quoteFromFile` itself was further changed to take into account the
changes in `Doc::quoteFromFile`, now resolving the file itself.
- Some of the code was littered with TODO and REMARK comments to keep
track of things that were noticed during the change that will not be
addressed at this point in time.
Change-Id: Ifb2e03696f6de64dac54470f7a969d323a88c0a7
Task-number: QTBUG-100381
Reviewed-by: Topi Reiniö <topi.reinio@qt.io>
|
| |
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
| |
`DocParser::IsAutoLinkString/1` is used to identify when a word, in its
entirety, qualifies for auto-linking.
Because of the way it is implemented, based on another overload of
`isAutoLinkString` and the way that overload is implemented, the method
would actually check if a prefix of the word qualifies for auto-linking.
What this meant is that at each call site, the method was respecting
its contract if and only if each word that was passed to it was formed
such that it would always be parsed in full.
For example, with the current implementation, `foo()Z`, where Z is any
string, would be considered to qualify for auto-linking.
This could further be problematic when the code around the call changes.
For example, since QDoc uses this overload when dealing with unknown
commands, behaving differently depending on the return value of the
method call, a change to the grammar for commands might expose this
behavior, with QDoc considering the entire word as qualifying for
auto-linking and not treating it as an unknown command.
To avoid the issue, the method was modified to ensure that the word was
parsed in full as a further requirement to having a prefix of the word
qualifying for auto-linking.
Some documentation was removed as it was outdated by the change.
Some incorrect wording in the documentation for `isAutoLinkString/2` was
changed to better reflect the behavior of the method.
Change-Id: I2d3e0058b6b395ab18a9b58aad977af965555bac
Reviewed-by: Topi Reiniö <topi.reinio@qt.io>
|
| |
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
| |
While parsing a QDoc block-comment, QDoc evaluates some sequences of
characters as candidates for auto-linking.
A sequence of characters that is considered for auto-linking will be
tried to be correlated with some documented element and presented, in
the final documentation, as a link to that element, if any such element
exists.
Up to now, the rules for auto-linking would qualify as a candidate
sequences of special characters such as "_", "____", "@_" or "()" to be
auto-linking candidate.
The production of those candidates could, in some currently unknown
conditions, be correlated with some documented elements, producing an
incorrect link in the output documentation.
See for example QTBUG-100562.
To avoid this issue, the rules were modified to such that identifier
that are composed of special characters require at least some part
composed of lowercase or uppercase characters to be considered as
candidates for auto-linking.
For example, `_` would not qualify for auto-linking while "QT_DEBUG"
would still qualify.
Code-wise, the method responsible for identifying auto-linking
candidates, `DocParser::isAutoLink`, would keep a count of the amount
of characters of a certain category that was encountered during parsing.
If any character in the category "StrangeSymbol", such as '_', was
encountered, in any position that was parsed, `isAutoLink` would
consider the passed in word as a valid candidate for auto-linking.
The condition was expanded to require at least one character in the
"lowercase" or "uppercase" category to be encountered together with the
"StrangeSymbol" for the passed in word to be considered a valid
candidate.
As a consequence of modifying the validation with regards to
"StrangeSymbol"s, part of the code was able to be simplified.
Before, it was required to check that the sequence "()", which is a
"StrangeSymbol", did not appear as the starting sequence of the word,
such as to avoid the recognition of the word "()".
Now, since a "StrangeSymbol" does not qualify for auto-linking, the
branching for the "()" case could be flattened as a word "()" will not
be considered a candidate and the parsing, as before, will stop after
encountering that sequence.
Some documentation for the current rules was embedded in the codebase.
Fixes: QTBUG-101711
Change-Id: I5c47ece85ac6c419b7fe048d55becb52ba61601b
Reviewed-by: Topi Reiniö <topi.reinio@qt.io>
|
| |
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
| |
The codebase for QDoc implements a command, 'quotefunction', that eases
quoting a specifying function from a currently being-quoted file.
The command is unused in Qt's documentation, is undocumented in the QDoc
manual and only appears as a string (but not a call to the command
itself), inside of the files used by `tst_generatedOutput`.
While, arguably, there might be some use to higher-level commands that
simplify common operations that might be done trough the use of the
`quotefromfile` family of commands, `quotefunction` itself is,
currently, no more than dead code, and is thus removed, knowing that it
can be reintroduced with ease should the need arise, as a mean to
simplify the upcoming changes to the quoting system.
`DocParser::slashed` is now removed as it was used only during the
processing of a 'quotefunction' command.
The machinery which supported this feature in the `CodeMarker` family of
classes, `functionBeginRegExp` and `functionEndRegExp`, was removed as
it is now unused.
The `quotefunction` string in the input data to `tst_generatedOutput`
was removed and the output was regenerated to take the change into
account.
Change-Id: Ied2b04e0f3f1a74ff60300e83e2a514de872b7cb
Reviewed-by: Paul Wicking <paul.wicking@qt.io>
|
| |
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
| |
Allow an arbitrary number (up to nine) of extra parameters to the
\include command, and replace the matching \1..\9 placeholders in
the quoted content with strings passed as parameters.
This enables reusing oft-repeated content but still customizing
each occurrence.
The original second argument for \include (the snippet id tag)
was constructed by taking everything up until a newline - the
extra parameters must however each be enclosed in braces to
support whitespace within a parameter. Keep the old syntax
functional as it is widely used although not explicitly
documented.
[ChangeLog][qdoc] QDoc now allows extra parameters for the
\include command to customize the quoted content.
Pick-to: 6.3
Fixes: QTBUG-48742
Change-Id: I03c7ae02660f090971e3ed769a62ed5ee18557f0
Reviewed-by: Luca Di Sera <luca.disera@qt.io>
Reviewed-by: Paul Wicking <paul.wicking@qt.io>
|
| |
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
| |
`\oldcode` and `\newcode` are a pair of commands that are used together
to show changes in API usage.
Due to the low amount of use for this feature and the arguable utility
of it, the command-pair is now deprecated and marked for removal in Qt
6.4.
A warning is added when an `\oldcode` command is encountered to warn
the user of the commands deprecation and the expected removal in the
near future.
The manual for QDoc was updated to notify of the deprecation and
soon-to-be removal.
`tst_generatedOutput` was updated to avoid referring to the command-pair
and the touched output files were regenerated.
Task-number: QTBUG-98499
Change-Id: I5af6a9ff8571d51418cad9bfe2567b8401f4dcae
Reviewed-by: Paul Wicking <paul.wicking@qt.io>
Reviewed-by: Topi Reiniö <topi.reinio@qt.io>
|
| |
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
| |
QDoc attempts to style links to C++ functions in a specific way,
by moving function arguments and the enclosing parentheses
out of the link. This was done in a way that had unintended
consequences for all link texts that included an opening
parenthesis, whether the link target was a function or not.
As a fix;
* Increase the specificity of the regular expression
used for identifying a function-like link text.
* Store the Node we're linking to in generator, so
we can match the regular expression only to function
targets, not all links. This is also a performance
improvement.
* DocParser: Stop generating AutoLink atoms inside an
open (explicit) link. This was useless as it split
the input into multiple nested link->autolink atoms,
and the nested ones are discarded/treated as strings
in the generator anyway.
* Refactor related generator functions and remove
obsolete debugging code.
Pick-to: 6.2
Task-number: QTBUG-97949
Change-Id: I89429a73f13aa9995a79dfd24a8e473c620d6bc6
Done-with: Luca Di Sera <luca.disera@qt.io>
Reviewed-by: Luca Di Sera <luca.disera@qt.io>
Reviewed-by: Paul Wicking <paul.wicking@qt.io>
|
| |
|
|
|
|
|
|
|
|
|
|
| |
And add Atom types for Warning instead of simply hard-coding a bold
warning note.
Fix a compiler warning for tst_generatedoutput in passing.
Pick-to: 6.2 5.15
Fixes: QTBUG-97448
Change-Id: I1fe691ffaadc549b17c8628817fe761d3be0fad7
Reviewed-by: Paul Wicking <paul.wicking@qt.io>
|
| |
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
| |
QDoc provides a mechanism for tagging specific function declarations
in a header with //! [tag] comments, allowing these tags to be
referenced in an \fn command. This feature did not work for
shared comment nodes containing multiple \fn commands, however.
To make this work, we need to associate the 'bracketed args' (where
the id tag is) with the command itself - previously it was stored
in the Doc instance, but that doesn't work when there are multiple
topic commands sharing a doc. To do so, repurpose the ArgLocPair
structure to store the bracketed arg instead of a Location, as we
never used this particular Location for anything, anyway.
Pick-to: 6.2
Fixes: QTBUG-95948
Change-Id: Ic899d4252d705f84ba56ea201a55f3e5db068f00
Reviewed-by: Paul Wicking <paul.wicking@qt.io>
|
| |
|
|
|
|
|
|
|
|
|
|
|
| |
* Unify members; use s_ or m_ prefix instead of _ suffix.
* Remove unnecessary member that duplicates content in base class.
* Add [[nodiscard]] annotations where applicable.
* Add overloads to virtual methods that have been extended with
parameters with default values.
* Make single argument ctors explicit.
* Remove semi-colon from namespace declaration.
Change-Id: Ie1ff39079722b81ba6754f945a898dc9b335bbae
Reviewed-by: Topi Reiniö <topi.reinio@qt.io>
|
| |
|
|
|
|
|
|
|
|
|
|
|
|
|
| |
Previous method did not correctly handle multi-line descriptions for
enum values omitted from the documentation which we have multiple
instances of in the source. These description paragraphs are now
skipped entirely.
After \omitvalue, skip all content until a new paragraph, a \value
command, or another \omitvalue.
Pick-to: 6.1
Task-number: QTBUG-92386
Change-Id: If9284ad2936019bc9afbfaa7cbf5cfbdbdd3cfa4
Reviewed-by: Paul Wicking <paul.wicking@qt.io>
|
| |
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
| |
This change allows users to specify an optional parameter
to the \deprecated command to record which version something
was deprecated. It also allows for free text descriptions.
These descriptions become the first paragraph of the resulting
documentation.
Usage:
\deprecated
\deprecated [6.2]
\deprecated [6.2] Use QFoo() instead.
\deprecated Use QFoo() instead.
[ChangeLog][qdoc] QDoc now lets you record the version something
is deprecated and suggest replacements with the \deprecated command.
Task-number: QTBUG-58249
Change-Id: I27081627132b2f8ea3dd7d48ded8e37213366074
Reviewed-by: Topi Reiniö <topi.reinio@qt.io>
Reviewed-by: Paul Wicking <paul.wicking@qt.io>
|
| |
|
|
|
|
|
|
| |
This command was undocumented and non-functioning; Remove it, the
related data structures and enum values.
Change-Id: Ia95efd20d35908ea5a23e660abb2b06b354f5f5a
Reviewed-by: Paul Wicking <paul.wicking@qt.io>
|
| |
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
| |
* Use multiple arguments for QStrings instead of calling
.arg() multiple times.
* Define trivial constructor/destructor '= default' instead of adding
empty implementations.
* Remove unreachable code.
* Prefer ranged-based for loops.
* Initialize with auto from static_cast<>() and new.
* Simplify expressions.
* Prefer "QList::empty()" over "QList::size() > 0".
* Remove unused method.
* Return qsizetype instead of int to avoid narrowing conversion.
* Remove unused include.
* Remove unreachable return statement.
* Prefer raw string literals over escaped regexes.
* Initialize struct members.
* Make variables used as const refs const refs.
* Use std::move instead of passing const ref in ctor.
* Drop redundant 'virtual' from methods marked 'override'.
* Make local copies that arent ever modified const refs to avoid copying.
* Turn for-loop into std::any_of.
* Made single-argument constructor explicit.
* Don't shadow variable names from outer scope if not necessary.
* Remove const at top level that does not improve const correctness.
* Update copyright notice for affected classes.
Task-number: QTBUG-71176
Change-Id: Ia41e5b947b72f594b60d189b6b0ff68587c3afb9
Reviewed-by: Topi Reiniö <topi.reinio@qt.io>
|
| |
|
|
|
|
|
|
|
|
|
| |
For \omitvalue <enum_value>, omit also single-line descriptions that
immediately follow <enum_value> or appear on a new line following the
\omitvalue command.
Pick-to: 6.1
Fixes: QTBUG-92386
Change-Id: Id8a70ff48102075d3b18442547773ae7f3eefefa
Reviewed-by: Paul Wicking <paul.wicking@qt.io>
|
| |
|
|
|
|
|
|
|
|
|
|
|
|
| |
- 'sources' configuration variable was not considered when searching
for file to include.
- An empty QString was pushed to the location stack in
DocParser::include(), resulting in vague warning messages
- The search algorithm chose the first path that ended in the
filename to find, with the potential of incorrectly choosing
'foobar.cpp' over 'bar.cpp'.
Fixes: QTBUG-86844
Change-Id: If180ffe0817b2e786356b49f7e679e158fbc407d
Reviewed-by: Paul Wicking <paul.wicking@qt.io>
|
| |
|
|
|
|
|
|
|
|
|
|
| |
Most of the dita code is removed, get rid of the last few
bits and the header that is no longer used.
[ChangeLog][qdoc] The obsolete \ditamap has been removed.
Task-number: QTBUG-71176
Fixes: QTBUG-86560
Change-Id: I7c65cc8a74d4caeabdc98d6852026f54a3c32dda
Reviewed-by: Topi Reiniö <topi.reinio@qt.io>
|
| |
|
|
|
|
|
|
|
|
|
|
|
|
|
| |
These small changes make the output of \footnote slightly more sane.
The command is not fully implemented; for HTML generator it produces
only <!-- --> comments, but the previous behavior was incorrect and
affected formatting of the rest of the document.
With WebXML output format, \footnote command together with \link (as
in the generatedoutput test) seem to differ in linefeed placement on
Windows as compared to other platforms. Remove these from the tested
set for now.
Change-Id: Id387aaeef1de1d1a859b5ec6e388394564cd0732
Reviewed-by: Paul Wicking <paul.wicking@qt.io>
|
| |
|
|
|
|
|
|
|
|
|
|
|
|
| |
The current implementation suffers from lack of maintenance. This
causes a poor user experience that adds little value, or is even
detrimental to perceived value. Work to improve the situation would
have to be done at the expense of something else.
This patch removes the Q_DECLARE_TR_FUNCTIONS macros from QDoc, and
replaces calls to tr() with QStringLiteral().
Fixes: QTBUG-84568
Change-Id: I2df71c27246ca5de816608c887cf359db8f85900
Reviewed-by: Topi Reiniö <topi.reinio@qt.io>
|
|
|
The bulk of Doc's implementation file is the DocParser class.
Extract this class to reduce the size and complexity of Doc, to improve
testability of both classes.
Fixes: QTBUG-84004
Change-Id: I44cc1ff50aaa7a29c06773761ed3860e1582926e
Reviewed-by: Topi Reiniö <topi.reinio@qt.io>
|
