summaryrefslogtreecommitdiff
path: root/src/qdoc/main.cpp
Commit message (Collapse)AuthorAgeFilesLines
* QDoc: Move QDoc source files under a further "qdoc" directoryLuca Di Sera2023-04-121-668/+0
| | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | 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: Flatten maps of source file in "main.cpp"Luca Di Sera2023-03-271-18/+15
| | | | | | | | | | | | | | | | | | | | | | | | | | When QDoc runs it collects a series of input source files based on certain configuration variables. The collected input source files are later used as the base for extracting the user-provided documentation. The files are collected into a map, in `processQDocConfFile`, `sources`. The map uses the same values, file paths that QDoc extracted from the above mentioned configuration variables, for each key-value pair. That is, given a file path X, `sources` stores a key-value pair X-X. Supposedly, the intention of using a map was to avoid duplicates. Indeed, the code that populates the map avoid inserting elements that already are present in the map, thus making use of the fast lookup that the data structure provides. As half of the map is left unused, indeed only the keys are ever accessed, we replace the map with a set, which better provides the required removal of duplicates. Change-Id: If4de2f1a6c8b45ac138139b7d49b1d0d73ed2c1f Reviewed-by: Paul Wicking <paul.wicking@qt.io>
* QDoc: Remove unused variable `sourceFileNames`Luca Di Sera2023-03-271-5/+0
| | | | | | | | | | | | | | | | | | When QDoc runs it collects a series of input source files based on certain configuration variables. The files are collected into two maps, in `processQDocConfFile`, `sources` and `sourceFileNames`. The collected input source files are later used as the base for extracting the user-provided documentation. Nonetheless, `sourceFileNames`, which is populated along with `sources` was never used and is thus removed as dead code. Change-Id: Ie02025e8b1054e4a4f3e9235ee1cc2d7631a2935 Reviewed-by: Topi Reiniö <topi.reinio@qt.io> Reviewed-by: Paul Wicking <paul.wicking@qt.io>
* QDoc: Clean up remains of incomplete translation effortPaul Wicking2023-03-231-48/+4
| | | | | | | | | | * Replace calls to QCoreApplication::translate() with QStringLiteral(). * Remove related configuration strings. * Remove #ifndef QT_NO_TRANSLATION blocks. Task-number: QTBUG-71176 Change-Id: If7ac4d84a757d75c8a36f94f1811391c81b56aff Reviewed-by: Topi Reiniö <topi.reinio@qt.io>
* QDoc: tiny cleanup in main.cppPaul Wicking2023-03-231-6/+3
| | | | | | | | | | | | Since recent refactoring removed the main use of the qdocFiles local variable, drop it in favor if accessing the source for that information directly through Config::instance(). Do the same for two other accesses through the local reference to Config::instance, thus allowing the removal of that reference. Task-number: QTBUG-71176 Change-Id: Id64d58cacc3b368d1986e12119a71cdbdc8d648a Reviewed-by: Luca Di Sera <luca.disera@qt.io>
* QDoc: Extract helper function in main.cppPaul Wicking2023-03-231-12/+18
| | | | | | | | | | | | | | | | | | | | | | | | Recent changes have extracted helper functions for running QDoc in single or dual execution mode, respectively. Both functions do minor setup, including getting a list of .qdocconf-files from `Config`. The setup and list of .qdocconf-files differ in these two execution modes. Both functions then loops over their list of .qdocconf-files. This loop calls clear() on Config's list of module dependencies before dispatching the qdocconf file to processQdocconfFile() for further processing. This loop is identical to both modes of execution; in single execution mode, this particular loop is performed twice. This patch extracts this loop as a separate function that accepts a list of .qdocconf-files it will iterate over. As this loop makes out the bulk of code in the two functions for execution modes, this implementation detail obscures the material difference of the work performed in the two callers of this new function. By extracting it, code readability is improved by letting the interesting parts take center stage. Task-number: QTBUG-71176 Change-Id: Ie7f63bde17d9b676f9755874537af6c5bb1f9c7e Reviewed-by: Topi Reiniö <topi.reinio@qt.io>
* QDoc: Extract dualExecutionMode function from main()Paul Wicking2023-03-231-5/+15
| | | | | | | | | | | | Recent refacoring extracted the executing code in QDoc's main() function for running QDoc in "single execution mode". This patch does the same for "dual execution mode", which is QDoc's default behavior. The result is a more expressive main() function, that is easier to reason about for code readers. Task-number: QTBUG-71176 Change-Id: I494f58cd0d424f4cde47cc0363f908f85aa44eac Reviewed-by: Topi Reiniö <topi.reinio@qt.io>
* QDoc: Extract singleExecutionMode function from main()Paul Wicking2023-03-231-15/+29
| | | | | | | | | | | | | | | | | | | In QDoc's main(), two identical conditional checks for whether QDoc runs in single execution mode follow each other. This patch extracts the contents of these conditionals and places them in a separate function, singleExecutionMode(). This in turn makes main() slightly easier to read and reason about. The new function is documented such that its purpose can be understood in clear terms. The list the function operates on is obtained from Config. As that is a singleton object, the function doesn't require the passing of a reference to that object, as it can access the required functionality directly through the singleton instance itself. The new function is therefore parameterless. Task-number: QTBUG-71176 Change-Id: I49fb571b99a24ff70ab8f0b17de8e1f44064e418 Reviewed-by: Topi Reiniö <topi.reinio@qt.io>
* QDoc: Extract function from main.cpp's processQdocconfFilePaul Wicking2023-03-231-11/+28
| | | | | | | | | | | | A recent change exposed a clear opportunity to extract a function from the rather large processQdocconfFile function in QDoc's main.cpp. This patch does that, and adds documentation for the new function so that it becomes clear for readers what goes on and what possible side-effects can occur. Fixes: QTBUG-112218 Change-Id: Id9084ee55250526679a47ff56b852d54569cb62c Reviewed-by: Topi Reiniö <topi.reinio@qt.io>
* QDoc: Remove `CppCodeParser` from the `CodeParser` hierarchyLuca Di Sera2023-03-221-6/+12
| | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | 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>
* QDoc: Remove `CodeParser::m_moduleHeader`Luca Di Sera2023-03-161-7/+2
| | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | 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: Remove unnecessary Config access functionsTopi Reinio2023-03-141-19/+19
| | | | | | | | | | | | | | | | | | 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>
* QDoc: Make global static in main local to functionPaul Wicking2023-03-131-8/+5
| | | | | | | | | | Move the global static ClangCodeParser into the one function that needs it, such that initialize/terminate behavior can be moved into ctor/dtor where it ought to be. Task-number: QTBUG-111686 Change-Id: I7034ba8ed302516e7d5dc36fcec1892d081f2072 Reviewed-by: Luca Di Sera <luca.disera@qt.io>
* QDoc: Move `CodeParser::parseHeaderFile` to `ClangCodeParser`Luca Di Sera2023-03-101-5/+7
| | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | 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: Remove Config::lastLocation()Topi Reinio2023-03-021-12/+5
| | | | | | | | | | | | | | | | | | | Config stored an internal Location, used for error reporting. This location instance was updated whenever a config variable was queried. This prevented parallelization of code that accesses Config via the singleton instance. Remove Config::lastLocation, and move functions that return a configuration variable as a string, string list, boolean, etc. to ConfigVar itself. Keep existing access functions in Config as simple wrappers. Provide Config::get() that returns a reference to ConfigVar, and provide location info via ConfigVar::location(). This allows call sites to get location info for a configuration variable on demand. Change-Id: I72c6f5cec699e44aa2f3164e6019a04adbd1ab07 Reviewed-by: Luca Di Sera <luca.disera@qt.io>
* qdoc: Make QDoc's output less noisy by defaultTopi Reinio2023-02-071-14/+14
| | | | | | | | | | | | | | | | | | | | | | | | | By default, QDoc printed progress information such as qt.qdoc: Start/Stop qdoc for <project> in <mode> qt.qdoc: Parse source files for <project> These do not provide much useful information, so hide them under the --log-progress command line option. --debug now also implies --log-progress. Remove all uses of leftover debug statements that used qDebug(), or where suitable, convert them to use logging category with qCDebug() and friends. Remove unused function FunctionNode::debug(). Clean up formatting and language for some of QDoc's output messages in passing. Fixes: QTBUG-110923 Pick-to: 6.5 Change-Id: I2cab456b0e144249e4234a253fd1c90d76666132 Reviewed-by: Topi Reiniö <topi.reinio@qt.io>
* Remove unused variablesPeter Varga2022-12-161-4/+0
| | | | | | | | Fixes Clang -Wunused-but-set-variable warning. Change-Id: Ieef44cd2ff6a2d5e56c3eee61ed89e8d79d0a200 Pick-to: 6.5 Reviewed-by: Kai Köhne <kai.koehne@qt.io>
* qdoc: Fix various clang warningsFriedemann Kleint2022-12-021-3/+4
| | | | | | | | | | | | - 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>
* Port from qAsConst() to std::as_const()Marc Mutz2022-10-061-4/+4
| | | | | | | | | | | | | | | 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>
* Port from container::count() and length() to size()Marc Mutz2022-10-061-1/+1
| | | | | | | | | | | | | | | | | | | | | | 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>
* QDoc: Remove support for javascript codeblocksLuca Di Sera2022-09-091-3/+1
| | | | | | | | | | | | | | | | | | | | 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>
* QtTools: port away from deprecated operator""_qs()Ivan Solovev2022-08-301-1/+3
| | | | | | | | 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>
* QDoc: port away from deprecated qSetGlobalQHashSeed(0)Ivan Solovev2022-08-291-1/+2
| | | | | | | | Use QHashSeed::setDeterministicGlobalSeed() instead Task-number: QTBUG-105102 Change-Id: Ice7207af09c24663311fc475d17fd6035e4d8734 Reviewed-by: Thiago Macieira <thiago.macieira@intel.com>
* qdoc: Fix CodeChecker warning about nullptr dereferenceTopi Reinio2022-08-091-3/+5
| | | | | | | | This was never a real issue as Location::fatal() terminates qdoc, but make an explicit check before dereferencing the pointer. Change-Id: I6f159b4d48ac6c2852943e69534122a2305265ec Reviewed-by: Luca Di Sera <luca.disera@qt.io>
* QDoc: prefer std::pair over QPairPaul Wicking2022-08-091-1/+1
| | | | | | | | | | | Following the replacement in DocBookGenerator, replace the use of QPair with std::pair across QDoc's code base for consistency. Pick-to: 6.4 Change-Id: I2fc9f5f730a1bc570133b07d9eabad56d27ed9e8 Reviewed-by: Luca Di Sera <luca.disera@qt.io> Reviewed-by: Thibaut Cuvelier <cuvelier.thibaut@gmail.com>
* QDoc: Rename .hpp files to .hLuca Di Sera2022-06-241-2/+2
| | | | | | | | | | | | | Recent additions introduced some .hpp files in QDoc and QDoc's testing. It is convention for the Qt project to only use .h files, albeit this was unknown at the time of introduction. To abide to the rest of the project, all first-party .hpp files were renamed to .h. Change-Id: Iec783bdf012da6fd9094c5d7b8271a56553921f6 Reviewed-by: Topi Reiniö <topi.reinio@qt.io>
* Use SPDX license identifiersLucie Gérard2022-05-191-27/+2
| | | | | | | | | | | 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>
* QDoc: Apply the FileResolver abstraction to the codeLuca Di Sera2022-05-101-23/+110
| | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | 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>
* QDoc: Code cleanupPaul Wicking2021-05-031-4/+1
| | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | * 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>
* qdoc: Remove unused functionality for link countingTopi Reinio2021-04-261-1/+0
| | | | | | | | Unused code was part of the QA-page feature which was already dropped in a previous change. Change-Id: Iac3c24dae5a39f4c5d7ec8285f8ac6c17c72e646 Reviewed-by: Paul Wicking <paul.wicking@qt.io>
* qdoc: Manage logging category in utilities.h/cppTor Arne Vestbø2020-09-241-3/+0
| | | | | Change-Id: I39ec66fbe95edc42a3dac51e8bc718ee42cc4a2a Reviewed-by: Paul Wicking <paul.wicking@qt.io>
* QDoc: Add Config::showInternal()Paul Wicking2020-09-021-1/+1
| | | | | | | | | Add simple getter to avoid unnecessary calls to Config::getBool(CONFIG_SHOWINTERNAL). Task-number: QTBUG-71176 Change-Id: I56ce19437327f8ceb698f4754ea8814d7245a4a6 Reviewed-by: Topi Reiniö <topi.reinio@qt.io>
* QDoc: Minor cleanup in main.cppPaul Wicking2020-06-251-9/+9
| | | | | | | | | | * prefer to call empty() over checking size() > 0 in QStringLists * write escaped string literal as raw string literal * rename variable in loop that shadows outer scope Task-number: QTBUG-71176 Change-Id: I3eed6e5e07260e2787892bc8abb5bb6e42eddc6c Reviewed-by: Mårten Nordheim <marten.nordheim@qt.io>
* qdoc: Respect --nolinkerrors when generating warningsTopi Reinio2020-06-151-10/+14
| | | | | | | | | | | | | | | There were multiple instances where QDoc still generated warnings for linking issues even with --nolinkerrors command line option or QDOC_NOLINKERRORS env. variable set. With linking errors disabled, disable warnings also for failures to locate index files; this is required to eliminate false positives when testing documentation builds in the CI as we won't have any .index files available during integration. Task-number: QTBUG-78069 Change-Id: Ib8b9bcbc3f9c3cf31f93f97254ab109d0f5ed22b Reviewed-by: Paul Wicking <paul.wicking@qt.io>
* QDoc: Use QList instead of QVectorJarek Kobus2020-06-091-2/+2
| | | | | | | | 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>
* QDoc: Clean up includesPaul Wicking2020-05-041-6/+2
| | | | | | | | | * Remove unused includes * Replace deprecated C++ includes with counterpart. Task-number: QTBUG-71176 Change-Id: Ie3224d9f9c19fd8f93879de6c7604a8db421b88b Reviewed-by: Topi Reiniö <topi.reinio@qt.io>
* QDoc: Clean up whitespace in log messagesPaul Wicking2020-03-091-2/+2
| | | | | Change-Id: Ib7dbb54c0a2d8ea7b754edc8fb7d2175471acc38 Reviewed-by: Topi Reiniö <topi.reinio@qt.io>
* QDoc: Clean up log messagesPaul Wicking2020-03-091-3/+3
| | | | | Change-Id: If65d87e520f228997a857dbbebc13d98fa9ce994 Reviewed-by: Topi Reiniö <topi.reinio@qt.io>
* QDoc: Disentangle Generator and ConfigPaul Wicking2020-03-041-9/+9
| | | | | | | | | | | | | | | | * Keep track of use of DocBook extensions in Config. * Let Location query Config about use of Timestamps in logging. * Set writeQaPages in Config and get it from there. * Let Location query Config about whether logging is enabled or not. * Let Config track if QDoc is running in single or dual exec mode. * Move phase information to Config and track the current phase state there. * Remove the inclusion of generator.h from config.cpp, clangcodeparser.cpp. Task-number: QTBUG-82106 Change-Id: I06c8aeb40417e5c83cfa693f5f1ab2c210d34469 Reviewed-by: Topi Reiniö <topi.reinio@qt.io>
* QDoc: Use logging category over logToStdErrAlwaysPaul Wicking2020-03-041-8/+7
| | | | | | | | | Use the logging category framework for all log messages that used to be issued by logToStdErrAlways. Remove the method so that it doesn't suddenly creep back in. Change-Id: I65131bd01b5c79d6eab9619d9bb9b7bf6ff279c1 Reviewed-by: Topi Reiniö <topi.reinio@qt.io>
* Merge remote-tracking branch 'origin/5.14' into 5.15Qt Forward Merge Bot2020-02-181-18/+29
| | | | | Change-Id: I98eaf748fdfb34f32d187718459327b8eef9c54b Reviewed-by: Topi Reiniö <topi.reinio@qt.io>
* qdoc: Make Config a singletonTopi Reinio2020-01-131-15/+18
| | | | | | | | | | | | 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>
* Implement DocBook support for qdocThibaut Cuvelier2020-01-031-0/+2
| | | | | | | | | | | | | | | | | | | | | | | | | The use of this code would be to overhaul the translation project of the documentation in French, for Developpez.com (which is now stuck at Qt 4.7 due to outdated tools: https://qt.developpez.com/doc/). This means that this code will be used and maintained, whatever the decision follows QTBUG-71493, for instance. The DocBook support is not 100% vanilla DocBook, as some tags are missing, but rather an extension (which could be officialised soon: https://github.com/docbook/docbook/issues/111). These tags are used to encode metadata about the code being commented (classes, fields, functions, etc.). More precisely, the required tags are: [enum|macro|namespace|typedef|union][|name|synopsis], enum[value|identifier|item], [specialized]template[id]. These extensions can be enabled by the docbook-extensions parameter. If you want to see the history: https://github.com/dourouc05/qttools/tree/dourouc05-qdoc-docbook Change-Id: I919976d8680b41c5ca69bdb79a0b824c29b89d05 Reviewed-by: Topi Reiniö <topi.reinio@qt.io> Reviewed-by: Paul Wicking <paul.wicking@qt.io> Reviewed-by: Martin Smith <martin.smith@qt.io>
* clang-format QDocPaul Wicking2019-12-171-50/+53
| | | | | | | | | | | | | | | | This patch is the result of formatting all of QDoc's source with clang-format. The clang-format style is from the qt5 super repo's _clang-format definition. The purpose is unify the style across the code, to avoid spending too much time on style related issues in reviews and cleanup patches. Future changes to QDoc can benefit from using git-clang-format in combination with the git commit hook provided in qtrepotools.git as mentioned in this email to the dev list: https://lists.qt-project.org/pipermail/development/2019-October/037682.html Change-Id: I8af6a051c8334b5f35862a4dcd3becce8ac500c2 Reviewed-by: Martin Smith <martin.smith@qt.io>
* QDoc: Minor cleanup in main.cppPaul Wicking2019-12-121-48/+42
| | | | | | | Simple cleanup to improve readability. Change-Id: If9ee2947ad76e64d230584a3cb36e51457f643c3 Reviewed-by: Topi Reiniö <topi.reinio@qt.io>
* QDoc: Use QVector instead of QListPaul Wicking2019-12-121-2/+2
| | | | | | | | | | | Replace the use of QVector in most of QDoc. Also, remove one redundant C-style cast to int for result from method call that returns an int. As this happened in a macro, the result is removing a whole bunch of nagging from code inspection. Fixes: QTBUG-80669 Change-Id: Ib1aed95e01eaddd1e1213a145e815a0c4753ac67 Reviewed-by: Mårten Nordheim <marten.nordheim@qt.io>
* QDoc: Clean up whitespacePaul Wicking2019-12-111-16/+16
| | | | | | | Fix minor whitespace issues accodring to style. Change-Id: Ie56e815f23f25ccb1b2ffb03780b9e4c6b9d25eb Reviewed-by: Topi Reiniö <topi.reinio@qt.io>
* QDoc: Clean up loops with iteratorsPaul Wicking2019-12-101-25/+17
| | | | | | | | | | | - Use ranged-based fors where applicable. - Use auto keyword for iterators. - Move a few variable declarations to where they're to be used. - Update docs where applicable. Fixes: QTBUG-80536 Change-Id: I859440b96428dec4ef108b01d391479d3f8dbd83 Reviewed-by: Topi Reiniö <topi.reinio@qt.io>
* qdoc: Ensure the output subdirectory is used for locating dependenciesTopi Reinio2019-11-181-14/+40
| | | | | | | | | | | | | | | | | | | | | | | | | | Commit 2b6c90317 allowed QDoc to load all available index files if 'depends = *' configuration was used. This could still fail when output from multiple modules is directed to the same location (single-dir output mode). QDoc correctly adds the output directory as a place to look for index files, but because that output directory is also added as a dependency, it was removed from the list of sub-dirs to look into once that dependency was processed. This meant that all the subsequent dependencies could not be located. Also, there's a fundamental difference in how we must resolve the dependencies; without .nosubdirs, QDoc takes the subdirectories of -indexdir entries and treats them as dependencies. With .nosubdirs, we need to look for actual .index files in the -outputdir and load all of them. Finally, move the logging line for 'depends = *' further down, so that we can print out the number of resolved dependencies. Task-number: QTBUG-80051 Change-Id: I35ff5c22e8e1f7e2b0c7de798531ad1c72813e51 Reviewed-by: Martin Smith <martin.smith@qt.io>
* qdoc: Allow a documentation project to load all available index filesTopi Reinio2019-11-141-3/+9
| | | | | | | | | | | | | | | QDoc recognized '*' as a valid input for the 'depends' qdocconf variable, with the intent to load all available index files. This did not work as we cleared the resolved dependencies by re-fetching the depends string from Config after resolving the dependencies. This fix is a backport of another commit that is targeted for the dev branch, but this useful already for 5.14. Fixes: QTBUG-80051 Change-Id: I1d752208078452f4b16b1d855cdb67b8cbabf1f4 Reviewed-by: Martin Smith <martin.smith@qt.io> Reviewed-by: Paul Wicking <paul.wicking@qt.io>
View Lorry Controller Status