| 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>
|
| |
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
| |
QDoc extracts the user-provided documentation from which its output is
generated from a variety of input source file based on a project
configuration.
Those input source file can be of a variety of formats, as long as QDoc
currently supports them.
When parsing those files, QDoc extracts format specific information,
such as information about the available elements in a C++ translation
unit, and all the QDoc language comment-block that form the actual
documentation.
The format specific elements that are extracted are lowered into an
internal representation, the `Node` hierarchy, that QDoc later uses to
perform sanity checks on the user-provided documentation or to
automatically generate certain documentation.
The QDoc comment-blocks are generally processed in place, and they, too,
are converted into an internal representation, partly filling a `Node`
data partly filling a `Doc` instance, and used during later stages to
generate the final output.
It performs this process through the `CodeParser` hierarchy.
The base `CodeParser` class provides an interface to parse certain
source file based on their extension.
Child classes of `CodeParser` implements the actual parsing based on the
format that they support.
`CppCodeParser`, a direct child of `CodeParser`, implements the semantic
for topic and meta commands in a comment block.
That is, it gives meaning to commands such as `\fn` and `\example`.
`ClangCodeParser`, a direct child of `CppCodeParser` and indirect child
of `CodeParser`, implements the logic to extract information from C++
source code.
`PureDocParser`, a direct child of `CppCodeParser` and an indirect child
of `CodeParser`, implements the logic to extract QDoc comment-blocks
from a ".qdoc" file.
Finally, `QmlCodeParser`, a direct child of `CodeParser`, implements the
logic to extract information from QML source files.
Both `ClangCodeParser` and `PureDocParser`, but not `QmlCodeParser`,
depends on `CppCodeParser`.
That is, as they process the found QDoc comment-block in-place during
their parsing, they use `CppCodeParser` to perform this processing.
Indeed, `CppCodeParser` is never itself instanciated, and is only
intended to provide the shared logic for `ClangCodeParser` and
`PureDocParser`.
At the same, since `CppCodeParser` purpose is not to actually parse any
source file, it doesn't respect, meaningfully, the interface for
`CodeParser`, mostly providing stub implementation for its pure virtual
methods to satisfy the compiler.
Due to recent, purposefully made, changes, `CppCodeParser` does not
depend, mostly, on any internal-only state of `CodeParser`, while
`ClangCodeParser` and `PureDocParser` do not depend on any internal-only
state of `CppCodeParser`, instead depending only on access to some of
its methods.
Hence, `CppCodeParser`, which does not respect the `CodeParser`
interface meaningfully, can be removed from the hierarchy, simplifying
it and reducing the implicit state and interface of the other members,
additionally moving the codebase forward in the intention of removing
the `CodeParser` interface and some of the shared-mutable state that
QDoc depends on.
Thus, `CppCodeParser` does not inherit anymore from `CodeParser`.
As a consequence, `ClangCodeParser` and `PureDocParser` now inherit
directly from `CodeParser`, flattening the hierarchy depth to one.
Certain pure virtual methods that were provided directly or indirectly
by `CppCodeParser` are now implemented directly in `ClangCodeParser` and
`PureDocParser` to satisfy the `CodeParser` interface.
In particular, `ClangCodeParser` now implements an empty
`terminateParser`, as before the `terminateParser` implementation only
referred back to `CppCodeParser::terminateParser`.
Similarly, `ClangCodeParser::initializeParser` does not refer back to
`CppCodeParser::initializeParser` anymore.
`PureDocParser` now implements empty `initializeParser` and `language`
methods, as, while required by the `CodeParser` inheritance, are
completely meaningless in the scope of the class.
The methods that `CppCodeParser` inherited from `CodeParser` are thus
removed.
That is, `CppCodeParser::initializeParser`,
`CppCodeParser::terminateParser`, `CppCodeParser::language` and
`CppCodeParser::sourceFileNameFilter` are directly deleted.
`CodeParser` objects are built once and registered into a static list
owned by `CodeParser`.
Their lifetime is then managed by the `initialize`/`terminate` methods
of `CodeParser`, manually.
As `CppCodeParser` does not respect this manual management anymore, the
processing performed in `initializeParser` was moved to its constructor
and the processing performed in `terminateParser` was moved to its
destructor.
In doing so a declaration for the destructor was added to
"cppcodeparser.h" and an implementation of it was added to
"cppcodeparser.cpp", replacing the `terminateParser` implementation.
Similarly, the defaulted constructor for `CppCodeParser` was removed in
favor of a custom one and its implementation replaces the implementation
for `initializeParser`.
The implementation for `CppCodeParser` made use of the `m_qdb`, a
pointer to the `QDocDatabase` singleton, which keeps a certain amount of
state that is necessary during parsing, instance-member provided by the
`CodeParser` class.
Due to the changes in the inheritance hierarchy, those usages were
modified to obtain an instance of the database directly in their scope.
In particular, `CppCodeParser::parseOtherFuncArg`,
`CppCodeParser::parseMacroArg`, `CppCodeParser::processTopicArgs`,
`CppCodeParser::processQmlProperties`,
`CppCodeParser::processMetaCommand` and
`CppCodeParser::processTopicCommand` were modified as such.
`CppCodeParser` made use of certain static methods of `CodeParser`.
Usages of those methods were modified to directly refer to the
`CodeParser` namespace as they are not implicitly available in the
relevant scopes anymore.
In particular, `CppCodeParser::processTopicArgs`, which referenced
`CodeParser::parserForLanguage` and
`processTopicCommands`/`processMetaCommand`, which referenced
`CodeParser::isWorthWarningAbout`, were modified as such.
Both `ClangCodeParser` and `PureDocParser` made use of `CppCodeParser`
methods in the call chain for the virtual `parseSourceFile` method, the
entry point to the parsing of a source file.
All the usages are required to process the extracted QDoc comment-blocks
in-place.
Due to the hierarchy changes, both objects do not have access to the
required methods anymore.
As this dependency cannot be directly removed at this point,
`CodeParser::parseSourceFile` interface was modified to require a
`CppCodeParser` instance, to allow for the required in-place processing.
Thus, `ClangCodeParser::parseSourceFile`,
`PureDocParser::parseSourceFile` and `QmlCodeParser::parseSourceFile`
had their signature update to respect the new interface.
`QmlCodeParser` does not make use of `CppCodeParser` provided methods
and thus had no implementation change for `parseSourceFile`.
`ClangCodeParser` makes direct usages of certain `CppCodeParser` methods
in `parseSourceFile` and was thus modified to access them through the
passed in `CppCodeParser` instance.
`PureDocParser` makes use of `CppCodeParser` methods in
`processQDocComments`, the actual processing logic for the parser, as
called by `parseSourceFile`.
Hence, `PureDocParser::processQDocComments` was modified to receive an
instance of `CppCodeParser`.
The instance is passed directly by `parseSourceFile` and each call to
`CppCodeParser` method was modified to use the passed in instance.
Certain methods for `CppCodeParser` that are accessed by either
`ClangCodeParser` or `PureDocParser` were protected.
To allow the access to continue now that the classes aren't related
those methods are now public under `CppCodeParser`'s interface.
In particular, `CppCodeParser::hasTooManyTopics`,
`CppCodeParser::processTopicArgs`, `CppCodeParser::processMetaCommand`
and the two overloads of `CppCodeParser::processMetaCommands` were
modified as such.
Due to `parseSourceFile` now requiring a `CppCodeParser` instance, its
only usage, in `processQDconFile`, was modified to obtain such an
instance.
The instance is built in-place, once per call, in the smallest scope
that respects those requirements near the call to `parseSourceFile`.
Precedently, the manual lifetime management derived by `CodeParser`
would scope a `CppCodeParser` implicit instance, as provided by
`ClangCodeParser` and `PureDocParser`, as the whole of
`processQDocConf`.
As the only usages of `CppCodeParser` is through direct calls to
`parseSourceFile`, the new scope, while smaller, still ensures that the
object is long-lived enough for its usages.
All state that `CppCodeParser` depends upon, as the `CodeParsers` is
either instance based or `processQDocConf` scoped and thus no semantic
changes should derive from the instancing scope.
The change, while invasive, is not expected to change any of the output
documentation for QDoc, preserving the same semantic as before.
Change-Id: Iae448be6c6975649044aa08ed334c73faa38bddf
Reviewed-by: Paul Wicking <paul.wicking@qt.io>
|
| |
|
|
|
|
|
|
|
|
|
| |
At some point, someone probably had an idea they wanted to pursue.
As that time is now several years ago, I'd be willing to bet what
that idea was is long lost knowledge. Drop the comments as they keep
triggering the "what was the intention here?" question, which
cannot be answered satisfactorily.
Change-Id: I2996e98ee125ed0b198ee90677de82b5986cf5a6
Reviewed-by: Luca Di Sera <luca.disera@qt.io>
|
| |
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
| |
`ClangCodeParser`, the class that takes care of handling and parsing C++
source files to extract the user-provided documentation, will try to
automatically find the element in the code that some documentation block
refers to if that documentation block has no topic command.
Whend doing so and failing, it will generally try to report a warning to
the user.
The warning is emitted based on certain conditions.
In particular, if the documentation block exposes a "\since" command,
a command that specifies from which version of the project the
documented element is available, and the version specified by the
command is a future version of the project, the warning is not emitted.
The current version of the project is provided by the configuration that
QDoc reads when compiling.
`ClangCodeParser` copies that version and keeps it stored in an
instance-scoped member, `m_version`, so that it can compare it to the
one provided by a "\since" command.
As `m_version` is used only for this comparison, which is located in a
single function call, we remove `m_version` and directly access the
value in the config, which is not expected to change at any point in the
execution of QDoc, in-place.
Hence, the `m_version` member was removed. Its initialiazation in
`ClangCodeParser::initializeParser` was removed as a consequence.
Furthermore, its single usage in `ClangCodeParser::parseSourceFile` was
supplanted with a direct access to the configuration stored version.
Change-Id: Ie607fa3b74b4f9c9e3fba82a98a8f2f601018f70
Reviewed-by: Topi Reiniö <topi.reinio@qt.io>
|
| |
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
| |
QDoc parses a series of source file in different languages and formats
to find the user-provided documentation.
The base parsing interface for elements that perform this process is
given by the `CodeParser` class, with the concrete implementation of the
process for different languages/formats give by its child classes.
`CodeParser`, as part of its interface, provides certain methods that
are only meaningful when processing specific programming languages
source.
For example, it exposes `CodeParser::setModuleHeader` and
`CodeParser::moduleHeader` which are used to provide an PCH-able header
file for the C++ headers that will be parsed for a project.
Those methods are implemented in the `CodeParser` base-class, along as
setter and getter for the instance-state `m_moduleHeader`.
Nonetheless, they are only meaningful when running through the
`ClangCodeParser` `ClangCodeParser` child class, which actually
implements the processing of C++ source files.
Those, `m_moduleHeader`, `setModuleHeader` and `getModuleHeader` are now
removed from `CodeParser`.
`ClangCodeParser` only requires knowledge of the module header in its
private method `CLangCodeParser::buildPCH`, where the module header is
used to actually produce a precompiled header that will later be used by
further call to Clang when parsing C++ source files.
Hence, instead of moving the `m_moduleHeader` instance state to
`ClangCodeParser`, `buildPCH` and its public entry point
`ClangCodeParser::precompileHeaders` were modified to require a
`QString` parameter that is equivalent to the original value set through
`setModuleHeader`, so as to reduce the of the state to its current
lowest.
The value of a "module header" is generally given through the
configuration for the currently built project and was previously
extracted in "main.cpp" and set through `setModuleHeader`.
As a consequence of the above changes, the code that took care of
setting the module header was modified to pass the relevant value
directly to the single call of `ClangCodeParser::precompileHeaders`.
Furthermore, the above code was moved directly adjacent to the call to
`precompileHeaders` so that it appears nearer to its usage site.
Change-Id: I1d4db2fba2807b69e23e182197a78796a2a4675f
Reviewed-by: Topi Reiniö <topi.reinio@qt.io>
|
| |
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
| |
QDoc parses a series of source file in different languages and formats
to find the user-provided documentation.
The base parsing interface for elements that perform this process is
given by the `CodeParser` class, with the concrete implementation of the
process for different languages/formats give by its child classes.
`CodeParser`, as part of its interface, provides certain methods that
are only meaningful when processing specific programming languages
source.
For example, it exposes `CodeParser::parseHeaderFile` whose purpose it
to provide an entry point for parsing C++ header files.
The method is only meaningfully implemented and used in the
`ClangCodeParser` child class, the class that actually implements the
processing of C++ source files.
Hence, the method is now removed from `CodeParser`'s interface and
directly exposed as part of the interface of `ClangCodeParser`, to
reduce the surface of the method and to reduce the dependencies between
`ClangCodeParser` and the `CodeParser` interface, which is generally
expected to be removed in the future.
`CodeParser` are, currently and temporarily, mostly initialized
statically and then retrieved through certain methods of the
`CodeParser` interface.
`CodeParser::parserForHeaderFile` is one such method that would retrieve
a `CodeParser` or child class instance that is able to parse an header
file.
Due to the removal of `parseHeaderFile` from `CodeParser` interface and
the fact that only one specific parser is able, and should be able, to
parse header files, `CodeParser::parserForHeaderFile` was removed.
Its only usage in "main.cpp", where it was called to retrieve the
already available `ClangCodeParser`, was modified to make use of
`ClangCodeParser` directly.
An auxiliary method, `CodeParser::headerFileNameFilter`, previously used
only by `CodeParser::parserForHeaderFile`, which provided a list of
extensions to identify what files could be accepted by a certain parser
as header files, is now removed as dead code.
A non-meaningful reimplementation of the `headerFileNameFilter` method
in `CppCodeParser`, a child class of `CodeParser`, was removed as of
consequence.
Similarly, the same method implementation in `ClangCodeParser` was
removed.
The filtering functionality that the method indirectly provided when
used by `CodeParser::parserForHeaderFile`, which is to be retained for
backward compatibility reasons, was moved to
`processQdocconfFile` in "main.cpp", where the header files that should
be parsed are gathered.
Instead of using the `headerFileNameFilter` method, the data that was
provided by it is now exposed as a static member of `ClangCodeParser`
and accessed directly when filtering is necessary.
Change-Id: Iff9a204627675aa7b34232c114945afceb8313ff
Reviewed-by: Topi Reiniö <topi.reinio@qt.io>
Reviewed-by: Paul Wicking <paul.wicking@qt.io>
|
| |
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
| |
QDoc parses a series of source file in different languages and formats
to find the user-provided documentation.
The base parsing interface for elements that perform this process is
given by the `CodeParser` class, with the concrete implementation of the
process for different languages/formats give by its child classes.
`CodeParser`, as part of its interface, provides certain methods that
are only meaningful when processing specific programming languages
source.
For example, it exposes `CodeParser::precompileHeaders` whose purpose it
to provide a PCH for parsing C++ source files.
The method is only implemented and used in the `ClangCodeParser` child
class, the class that actually implements the processing of C++ source
files.
Hence, the method is now removed from `CodeParser`'s interface and
directly exposed as part of the interface of `ClangCodeParser`, to
reduce the surface of the method and to reduce the dependencies between
`ClangCodeParser` and the `CodeParser` interface, which is generally
expected to be removed in the future.
Change-Id: I243b81974c741589e7f644e1996cdb274e20502b
Reviewed-by: Paul Wicking <paul.wicking@qt.io>
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>
|
| |
|
|
|
|
|
|
|
|
|
|
|
|
| |
If multiple subprojects of a subdirectory project have files with the
same name, QDoc will not recognize them properly. It replaces the
previous file path with the later identified file. And the contents of
the tmpHeader file in the clang_parseTranslationUnit2 function don't
contain all files of the same name.
Fixes: QTBUG-95981
Pick-to: 6.2
Change-Id: Ic65f568ea89a6933c155a36f7f374627bff13555
Reviewed-by: Qt CI Bot <qt_ci_bot@qt-project.org>
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>
|
| |
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
| |
* 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>
|
| |
|
|
|
|
|
| |
Clang's diagnostics are silenced unless debug is enabled with --debug.
Change-Id: I1c79c56b6f0d4fd676de99c4a00c951499d4e3a6
Reviewed-by: Paul Wicking <paul.wicking@qt.io>
|
| |
|
|
|
|
|
|
| |
Task-number: QTBUG-84469
Change-Id: I88b99ba7f5648d9da7878b7f7723f48cd86be2ac
Reviewed-by: Friedemann Kleint <Friedemann.Kleint@qt.io>
Reviewed-by: Paul Wicking <paul.wicking@qt.io>
Reviewed-by: Topi Reiniö <topi.reinio@qt.io>
|
| |
|
|
|
|
|
|
|
|
| |
* Prefer m_ prefix over _ suffix for consistency.
* Use s_ prefix for static.
Coverity-Id: 226112
Task-number: QTBUG-79116
Change-Id: Iee15a8e5b257a5b6627715cba23e5c76542dfc29
Reviewed-by: Topi Reiniö <topi.reinio@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>
|
| |
|
|
|
|
|
|
|
|
|
|
|
|
|
| |
When using an \fn command to document a function that has default
values for parameter(s), The Clang parser retrieves a relevant
section of the source file that contains the expression for the
default value. In case of \fn, the source is a temporary translation
unit that was constructed on the fly - but it may not exist anymore,
and the default value is lost.
Fix this by storing the contents of the temporary TU for later access.
Fixes: QTBUG-83472
Change-Id: I20ad9e3322636450db1def65933837c1c767f2c4
Reviewed-by: Paul Wicking <paul.wicking@qt.io>
|
| |
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
| |
Writing \fn commands for member functions of classes declared under
a namespace was error-prone as QDoc required the fully qualified
paths for the function signature, even though the documentation
comment was located under the correct namespace scope.
Store the scope by backtracking the Clang AST until we reach the
level of the translation unit, and store each encountered namespace
declaration into a list. When generating the temporary source file
for an \fn command, we can then recreate the correct namespace
hierarchy.
This does not break the existing \fn command usage as it's perfectly
valid, even if unnecessary, to provide fully qualified paths in the
function signature.
[ChangeLog][qdoc] QDoc is now aware of the namespace scope of an \fn
command without requiring fully qualified paths.
Fixes: QTBUG-82190
Change-Id: Ia446c19d130b2ef48b16b67e4dfcbdaab1f9d4f5
Reviewed-by: Paul Wicking <paul.wicking@qt.io>
|
| |
|
|
|
|
|
|
|
|
|
|
| |
There is no need to pass a pointer to Config throughout
the API; the only instance of it is created in main()
so we can turn it into a singleton.
Having access to Config without API changes makes
implementation of configurable features easier.
Change-Id: Ida47e067865082dfe036a7a97f7f1ffc736db346
Reviewed-by: Paul Wicking <paul.wicking@qt.io>
|
| |
|
|
|
| |
Change-Id: I81de861e9daa00249c47ddbe259f43f47d7c6615
Reviewed-by: Paul Wicking <paul.wicking@qt.io>
|
| |
|
|
|
|
|
|
|
|
|
| |
This change removes reduntant destructors. It also adds the
'override' keyword to overridden destructors to remove warnings
from clang-tidy in Creator.
The patch also replaces two instances of 0 as nullptr constant.
Change-Id: I576c248b7d4637249d167d7bfb8885af4f7811ff
Reviewed-by: Edward Welbourne <edward.welbourne@qt.io>
|
| |
|
|
|
|
|
|
|
|
|
| |
Ensure that QDoc conforms to Qt style, whitespace edition.
For the most part, the change involves moving the pointer operators.
Also remove whitespace following an opening parenthesis, or
immediately preceding a closing one. In some cases, adjust the
following line accordingly in methods that span multiple lines.
Change-Id: I56ae125a2acf09c669c0a73dc814d05f13575f39
Reviewed-by: Martin Smith <martin.smith@qt.io>
|
| |
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
| |
Housekeeping. Includes are organized after recommended best practice and
organized in the following order:
- include self (i.e. include own header)
- include local files
- include Qt, e.g. <QtCore/qstring.h>
- include Qt private
- include externals, e.g. stdio.h
in alphabetic order within each block, aside from accommodating #if-ery,
in which includes follow the block they belong to.
Also, updated copyright notice to year of latest edit in each file.
Change-Id: I1e6b215f172fd5373d57016f7678b88b9e73231e
Reviewed-by: Edward Welbourne <edward.welbourne@qt.io>
|
| |
|
|
|
|
|
|
|
|
|
|
|
|
|
|
| |
When the build system can't pass qdoc the include paths to qdoc,
qdoc tries to guess reasonable include paths. There has been one
case running qdoc on macOS for the QtPlatformHeaders module, where
qdoc must try to guess the include paths. The guessed paths are
not sufficient, and clang prints a large number of errors caused
by missing stuff. This change tells clang not to report errors
during the PCH build if qdoc had to guess the include paths.
qdoc reports in its log that it guessed the include paths and
that it turned off the clang error reporting.
Change-Id: I91a4242dcc7d3017d511d969621cc3d673c47963
Reviewed-by: Paul Wicking <paul.wicking@qt.io>
|
| |
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
| |
Some function declarations are marked as not existing until Qt 6.0
in both the .h and .cpp files, but they are documented in the .cpp
file. qdoc can't tie the documentation for these functions to their
declarations because of the way clang is used, and qdoc reports
that reports the documentation as an error.
This update let's qdoc ignore these functions and not print the error
when they are marked with \since 6.0. This will also work with other
future versions.
This update also collects all the uses of #define COMMAND_xxx in one
location, which was partially required by the \since 6.0 change.
Change-Id: I55052359f387406da340c748768f8e76c0b39d53
Reviewed-by: Paul Wicking <paul.wicking@qt.io>
Reviewed-by: Topi Reiniö <topi.reinio@qt.io>
|
| |
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
| |
This change enables qdoc to print better log messages. A new logging
function is added to Location, where the qdoc error and warning
functions are located. The new function is logToStdErrAlways(msg).
It always formats msg for output to stderr by prepending the current
time and the word LOG. Several LOG messages are now sent to stderr.
Also, qdoc now always tells clang to output its parsing errors to
stderr during the building of the precompiled header in the prepare
phase. These clang parser errors are easily identified in the new
LOG.
When no include paths are passed to qdoc on the command line, which
is the case for QtPlatformHeaders, qdoc guesses some reasonable include
paths from the information available and passes them to clang. It works
ok for the QtPlatformHeaders module. However, clang gets lost in some
NSOpenGL headers and prints quite a lot of useless parse errors, so
we arbitrarily turn off clang's parse errors whenever qdoc has to guess
the include paths.
The guessed include paths are printed in the LOG, and a warning that
clang does not print parse errors when the include paths are guessed
is also printed in LOG.
Change-Id: I8e5bd0cc5b27463c4c85c9cdcc01b030ac03a1c1
Reviewed-by: Martin Smith <martin.smith@qt.io>
Reviewed-by: Paul Wicking <paul.wicking@qt.io>
|
| |
|
|
|
|
|
|
|
| |
Match interesting headers by file names in case mismatches
occur between installed headers and headers in the source tree.
Task-number: PYSIDE-620
Change-Id: Ie36fbd46fda38c86d88a00a992cac2fb58dd76bc
Reviewed-by: Martin Smith <martin.smith@qt.io>
|
| |
|
|
|
|
|
|
| |
old header.LGPL21 was used in few src files. Replace those with correct
header.LGPL one
Change-Id: I8333e14f89bd8175c98db6c60803c7c131448cbc
Reviewed-by: Topi Reiniö <topi.reinio@qt.io>
|
| |
|
|
|
| |
Change-Id: I5e164ea567ad7bef4b40112cf7665a0adfd91b55
Reviewed-by: Martin Smith <martin.smith@qt.io>
|
| |
|
|
|
|
|
|
|
|
|
|
|
|
|
| |
Because processing these commands do not use clang, their implementation
is moved from ClangCodeParser to CppCodeParser - this ensures
that these topic commands are processed also when they appear in
.qdoc files (PureDocParser, used for .qdoc, derives from CppCodeParser).
Also, these functions did nothing when qdoc was running in prepare
phase which in turn meant that they were not written to .index, thus
breaking cross-module linking for macros/QML methods/signals. That
check is now removed and the functions always do their thing.
Change-Id: I8d9333b02092708955b619b573254eda5d82f038
Reviewed-by: Martin Smith <martin.smith@qt.io>
|
| |
|
|
|
|
|
|
|
|
| |
This change replaces the last uses of qdoc's old, ad hoc
C++ parser. Clang is now used for parsing all C++ code.
\macro, \qmlxxx, and \jsxxx commands are parsed by simple
pattern matching functions using QString::split().
Change-Id: If6f95b0487d1dd3206373bc55ec8e6b8b9c55b1e
Reviewed-by: Edward Welbourne <edward.welbourne@qt.io>
|
| |
|
|
|
|
|
|
| |
qdoc now uses clang to parse \fn commands. It even handles the multiple
\fn case.
Change-Id: I259fcdfc1bf180d32ef1cc9886a48aa3006e18fb
Reviewed-by: Martin Smith <martin.smith@qt.io>
|
| |
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
| |
The PCH for module QtPlatformHeaders was not being built
because there are no .cpp files there, and clangqdoc was
only building the PCH when it was asked to parse the first
.cpp file. Now it builds the PCH by a direct call from the
main.cpp file, after the headers have been gathered into a
list, but before the .cpp files are parsed.
This does reduce the qdoc error count by a few, but it does
not fix the documentation for QtPlatformHeaders. From my
debugging, it appears that visiting the PCH produces no qdoc
nodes for the C++ classes and functions, etc in the PCH.
This update also improves the selection of default include
paths when inadequate include paths are provided. That is
the case for module QtPlatformHeaders, where no include
paths are provided. The algorithm for constructing a list
of reasonable guesses is modified here.
Change-Id: I0dee8dc0279894a4482df30703657558cdb098de
Reviewed-by: Topi Reiniö <topi.reinio@qt.io>
|
| |
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
| |
The qdoc 'defines' config variable lists values
that contain '*' to represent wildcards, but clang
doesn't accept them. This change adds a new config
variable called 'clangdefines' which explicitly
lists all the defines that match the wildcards.
It also lists several Qt defines for C++11 stuff,
because when clangqdoc comes into use, all the
supported compilers for Qt will support C++11
constructs.
There might be a few defines listed in clangdefines
that are unnecessary and maybe a few that we really
should not include, but we can adjust the list as
needed.
Also included in this change: Tell clang never to fail
(i.e. keep parsing no matter how many errors are found),
and tell clang not to print parsing errors, because they
obscure the qdoc errors in the output. clangqdoc should
assume that the source files are correct, but some of the
include files, especially system level stuff, will not be
present. clangqdoc doesn't care about these missing files,
because they aren't part of the documentation.
Change-Id: I84e1cae24d961a82d16ee705333d6f36955d35de
Reviewed-by: Topi Reiniö <topi.reinio@qt.io>
|
|
|
The file qt_find_clang.prf is inspired by qtcreator's clang_installation.pri.
The code from the while loop in ClangVisitor::parseProperty contains code
moved from CppCodeParser::matchProperty. The code in the for loop of
ClangCodeParser::parseSourceFile (from the "Doc parses the comment"), is mostly
moved from CppCodeParser::matchDocsAndStuff.
In CppCodeParser, most of the code is removed since clang is used for parsing.
We just need to leave enough to parse the declaration in the comments which
still use the old parser (\fn, ...)
Known issues:
- When the parameter name is a comment, it is lost.
(e.g. QObject::eventFilter(QObject * /* watched */, QEvent * /* event */)
- I can't compute default parameters when they are expanded from a macro.
(e.g. QObject::tr)
- Instances of #ifndef Q_QDOC need to be reviewed
Change-Id: I92d4ca4fc52810d9d3de433147a9953eea3a1802
Reviewed-by: Topi Reiniö <topi.reinio@qt.io>
|
