summaryrefslogtreecommitdiff
path: root/src/qdoc/generator.cpp
Commit message (Collapse)AuthorAgeFilesLines
* QDoc: Move QDoc source files under a further "qdoc" directoryLuca Di Sera2023-04-121-2099/+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: Warn about documented global functions that generate no docsTopi Reinio2023-03-241-3/+10
| | | | | | | | | | | | | | | | | | | | | | | | Generator::generateDocumentation() recursively traverses the tree of PageNode objects, i.e. nodes that generate output. However, it did not check if there are documented nodes in the global scope (root namespace) that generate no output. A typical case where this happens is global functions, where the author forgot to associate the function to something using the \relates command. Make QDoc print out a warning for these nodes, and mark them to have 'DontDocument' status so they will be ignored later on for linking and inclusion in the .qhp file. Also in Generator::generateDocumentation(), rename a variable local to a for-loop from 'node' to 'child', to prevent shadowing a 'node' in the outer scope. Pick-to: 6.5 Fixes: QTBUG-112256 Change-Id: I74fcc704f6848fc1eef8529da80f57678a83766e Reviewed-by: Paul Wicking <paul.wicking@qt.io>
* qdoc: Fix auto-generated \since note for \enum documentationTopi Reinio2023-03-221-4/+2
| | | | | | | | | | Drop the wording 'modified in x.y' from auto-generated note for \enum with a \since. Modifying an enum is now handled with \value since-clauses, and updating the \since version for the parent \enum would be incorrect. Fixes: QTBUG-108246 Change-Id: I6f32d14d108a1a71d0c0efc185f390617f0ba3cb Reviewed-by: Luca Di Sera <luca.disera@qt.io>
* qdoc: Remove unnecessary Config access functionsTopi Reinio2023-03-141-13/+14
| | | | | | | | | | | | | | | | | | 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: Remove Config::lastLocation()Topi Reinio2023-03-021-23/+19
| | | | | | | | | | | | | | | | | | | 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>
* Doc: Remove duplicate wordsAndreas Eliasson2023-02-091-1/+1
| | | | | Change-Id: If596f8677bbebba160e740dfcc24bba064dcb85f Reviewed-by: Leena Miettinen <riitta-leena.miettinen@qt.io>
* qdoc: Make QDoc's output less noisy by defaultTopi Reinio2023-02-071-17/+3
| | | | | | | | | | | | | | | | | | | | | | | | | 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>
* QDoc: Tag C++ elements as "noexcept" when they are marked as suchLuca Di Sera2023-01-251-0/+29
| | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | C++'s allows certain declarations to be marked by the `noexcept` specifier, so as to signify that the element will not throw any exception. A `noexcept` specifier might be unconditional, such the the relevant element is always to be considered "noexcept", or conditional, such that the element is or is not "noexcept" based on the evaluation of a compile-time, user-defined expression. This information is important to the user of an API, as it may dictate when and how they can use a certain element. Nonetheless, up to now, QDoc would not treat the "noexcept" specifier, such that this information was lost between source-code and documentation. To avoid the issue and ensure that users are given a way to discern whether something is marked "noexcept" or not, QDoc will now "tag" a relevant documentable element that is a callable, such as a C++ method, as "noexcept" when the `noexcept` specifier appears in its declaration or the element is implicitly noexcept (e.g destructors). To store this information, `FunctionNode`, the internal representation for "callable" documentable elements, such as a C++ constructor or method, was modified to expose an optional string, `m_noexcept`, trough the setter, `markNoexcept` and the getter, `getNoexcept`. `markNoexcept` allows the element as being "noexcept". Optionally a string can be provided which represents the expression of a conditional "noexcept". `getNoexcept` returns an optional value. If the value is Nothing, the element is to not be considered "noexcept". If the value is Just, it will contain a string that represents the condition under which the element is "noexcept". An empty string is to be considered marking a non-conditional "noexcept". Generally, this kind of information is extracted from the codebase in `ClangCodeParser::processFunction`, where an instance of a `FunctionNode` is populated based on the Libclang-provided `CXCursor` that generated it. LibClang has only partial support for the `noexcept` specifier. It allows the extraction of a `CXCursor_ExceptionSpecificationKind`, which provides information about the present or not of a `noexcept` specifier, but it doesn't provide a direct way to extract the expression of a conditional `noexcept` specifier. The expression of a conditioanl `noexcept` specifiers should generally be, in some way, presented to the user, as the user would not otherwise be able to ascertain whether an element is "noexcept" or not in its use case, thus requiring us to extract it in some way. For similar issues, we have generally taken to tokenizing the source code to manually extract the required information. For the specific case of a `noexcept` specifier, we consider this unfeasible due to grammar of of the C++ language. In a function signature, in particular due to the existence of the `noexcept` operator, an operator that returns whether an expression is "noexcept" or not, the `noexcept` keyword can appear many times, in many places with different meanings. The extraction of the very specific `noexcept` specifier, and its expression should it be conditional, is thus hindered so that it is not easy to cover all possible cases without actually parsing the signature itself. To be able to find the information we are looking for, we drop down from LibClang's to clang's C++ AST, which provides full support for this kind of extraction. To do so, a new function, `get_cursor_declaration`, is added to "src/qdoc/clangcodeparser.cpp". Each `CXCursor` in LibClang stores a reference to the C++ AST element that generated it. `get_cursor_declaration` extracts this information, for CXCursors that represent a declaration, and returns the underlying C++ AST node, which can be used to access the more thorough functionalities that the C++ AST provides. `ClangCodeParser::processFunction`, was modified to call `get_cursor_declaration` for its processed elements. From the retrieved declaration, the normal methods of the C++ AST are used to extract information about the presence, or lack thereof, of a `noexcept` specifier and its expression, should it be conditional. This information is then stored into the processed `Node`, using the newly introduced `markNoexcept`. Later on, during the "Generation Phase", where QDoc destructures the provided documentable elements to produce the final output documentation, QDoc will call a `CodeMarker` to generate the set of "tags", small strings that appear near the detailed documentation of an element, to enhance the final documentation with certain information about the documented element. To make use of the now stored "noexcept" information, `CodeMarker::extraSynopsis`, which is the particular methods that generates the relevant set of "tags" for an element, was modified to take into account the "noexcept" information of a `FunctionNode`. If the `FunctionNode` is marked as "noexcept" a tag will be produced. If the "noexcept" is not conditional, a "noexcept" tag is produced. If the "noexcept" is conditional, a "noexcept(...)" tag is produced. When this is the case, additional information will be generated for the detailed documentation of the relevant element to provide more information about the conditionality of the "noexcept". That is, a not will be produced that contains the expression that the "noexcept" is conditioned on. To do so, a new method `generateNoexceptNote` was added to `Generator`, the base class of the components that take care of producing the effective output during a QDoc execution. The method is implemented using the same pattern of similar procedures, such as `Generator::generateSince`, where, starting from the processed `Node`, a `Text`, an internal representation for certain formatted output, instance is produced and delivered to `Generator::generateText`, which takes care of producing the marked-up output documentation. In particular, a note element containing the extracted conditional expression and a small text about the lack of exceptions depending on this expression is produced. `HtmlGenerator`, the child class of `Generator` that specifically generates the HTML formatted output documentation, was modified to call the `Generator::generateSince` method when producing the detailed documentation of an element. The conditional expression for a `noexcept` specifier, while necessary for the user to see, might not necessarily be legible without additional context. This context cannot generally be auto-generated and, thus, the specific format in which we present this information is not to be considered final and is expected to change in the near future. When QDoc parses the source code for a project, it generates an XML-based "index" file, containing certain information about the extracted documentable elements that can be consumed by external tools and is consumed by QDoc itself to enable cross-module linking. To allow the newly added "noexcept" information to be retained between modules and to enable the inspection of such information for external consumers, `QDocIndexFiles::generateFunctionSection`, which writes the relevant information about a `FunctionNode` in the index file, was modified to write a "noexcept" attribute in the XML-element representing the `FunctionNode`. The attribute is elided when the `FunctionNode` is not marked as "noexcept", the default state, to save space and avoid cluttering the output. If the "noexcept" is conditional, a further attribute, "noexcept_expression" is written, containing the extracted conditional expression of the "noexcept". Similarly, `QDocIndexFiles::readIndexSection`, which retrieves the information stored in a certain index file and rebuilds the internal representations that QDoc uses for the represented elements, was modified to read the "noexcept" and "noexcept_expression" attributes that were added. If the "noexcept" attribute is present and has a "true" value in a "function" element, the reconstructed `FunctionNode` will be marked as "noexcept", to retain the information. If the "noexcept_expression" attribute is present, the `FunctionNode` will further contain a copy of the conditional expression in string form. The regression files for `tst_generatedOutput` were regenerated to take into account the addition of the new tag. Fixes: QTBUG-93439 Change-Id: Ic6e15c53309db6c4f398c15670fe3f15886bca3e Reviewed-by: Qt CI Bot <qt_ci_bot@qt-project.org> Reviewed-by: Topi Reiniö <topi.reinio@qt.io>
* QDoc: Remove unused overload of \meta commandPaul Wicking2022-12-301-20/+0
| | | | | | | | | | | | | | | At some point, special processing of meta content was added to make QDoc generate an entry of maintainer(s) in output. However, this hasn't seen use in the docs going back as far as _at least_ Qt 4.8. Remove this overload of the \meta command as it is unused, and adjust the relevant documentation in the QDoc manual. Pick-to: 6.5 6.4 6.3 6.2 6.1 6.0 5.15 Fixes: QTBUG-109724 Change-Id: I9890a831f0c950c122eced62e2e1b184bda23b0b Reviewed-by: Topi Reiniö <topi.reinio@qt.io>
* qdoc: Unify handling of QML types and QML value typesTopi Reinio2022-12-121-22/+9
| | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | QML value types, formerly known as basic types, are nowadays provided by multiple modules and contain also properties and methods. QDoc's support for value types was rather basic (pun intended): No import/since statements nor sections for properties etc. was generated, the reference page had essentially a flat structure similar to a generic \page. As QML and QML value types are closely related, eliminate the dedicated Node subclass for value types (QmlValueTypeNode), handle both with QmlTypeNode class, differentiating them only with NodeType enumeration. Make Node::isQmlType() return true for both to provide similar behavior for all QML types, with a few exceptions: * Do not warn if \qmlvaluetype command is missing \inqmlmodule info as many of the original value types do not document it * Do not generate 'all members' file for value types as they're not expected to inherit other types. * Do not include the QML module name qualifier into the filenames generated for value types. This is done in order to keep the existing behavior for value types and to avoid creating redirects for online documentation. Related to the last point, remove code from Generator::fullDocumentLocation() that was never executed as it was a duplicate from Generator::fileBase(). Unifying the types under a single Node subclass allows for removal of multiple functions and code paths related to value types. They have some constraints compared to proper QML types, but QDoc does not currently enforce them. [ChangeLog][QDoc][QDoc now properly outputs documentation for QML value types with properties and methods.] Pick-to: 6.4 Fixes: QTBUG-109132 Change-Id: I418660b0a6e0461c82fd5cb67e4f955a0d9a712c Reviewed-by: Topi Reiniö <topi.reinio@qt.io>
* qdoc: 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>
* qdoc: Fix clang warnings about lambdas returning QStringBuilderFriedemann Kleint2022-12-021-1/+1
| | | | | | | Pick-to: 6.4 Change-Id: Ib68ac437e2583c8f75a18b607548f147cebd3863 Reviewed-by: Topi Reiniö <topi.reinio@qt.io> Reviewed-by: Luca Di Sera <luca.disera@qt.io>
* Insert missing ends of paragraphs for reimplementsThibaut Cuvelier2022-11-041-29/+28
| | | | | | | Also simplify the code of generateReimplementsClause by merging two conditions. Change-Id: I04c7ffc774b885ce2da862557d7a3c3325901624 Reviewed-by: Paul Wicking <paul.wicking@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-17/+17
| | | | | | | | | | | | | | | | | | | | | | 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 unfinished support for documenting javascriptLuca Di Sera2022-09-071-43/+22
| | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | 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>
* QtTools: port away from deprecated operator""_qs()Ivan Solovev2022-08-301-2/+4
| | | | | | | | 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: Store BINDABLE property members into PropertyNodeTopi Reinio2022-08-231-7/+7
| | | | | | | | | | | | | | | | | | | | QDoc already recognized the BINDABLE attribute of Q_PROPERTY but did not store the name of the associated member. Store it in the list of a PropertyNode's access functions. This information will be useful later when deciding on whether to generate a warning for missing member functions; functions that are associated with properties can be left undocumented if the property itself is documented. Add a static helper function PropertyNode that returns the names of property access function roles. This is used when writing the access functions into an .index file. Convert access function-related enums to enum classes. Change-Id: Idd59622a965895883acf3ae297297ba3f3cca20e Reviewed-by: Luca Di Sera <luca.disera@qt.io>
* doc: Handle macros while generating since infoVenugopal Shivashankar2022-08-221-0/+3
| | | | | | | | | | | | | The generator treated macros as a function/method, resulting in a since entry that referred to the macro as a function. In addition, updated test data to ensure that the since entry for a \macro is tested. Change-Id: I648511705babad84163bc3e0ebd8233c4d46f4e2 Pick-to: 6.4 6.3 6.2 Fixes: QTBUG-105097 Reviewed-by: Topi Reiniö <topi.reinio@qt.io>
* Use registerRef to ensure xml:id validity and unicityThibaut Cuvelier2022-08-221-3/+18
| | | | | | | | | | | | | | | | | | | | Before this change, invalid xml:id were generated: - duplicates (several tags having the same xml:id -- not several ones pointing at the same ID, which is fine) - invalid characters (mostly spaces) - IDs not starting with a letter or an underscore (in particular, digits are not allowed in XML) - colons in IDs. Only few occurrences of this problem: - https://doc.qt.io/qt-6/qglobalstatic.html#operator-QGlobalStatic::Type--2a - https://doc.qt.io/qt-6/qflags.html#operator-QFlags::Int A flag controls the changes that are applied on IDs, so that there should be no changes for HTML IDs (very lax). Furthermore, stop using registerRef when it is not needed and clear the set of generated xml:id for each new document. Pick-to: 6.4 Change-Id: I53b08ae884a4e360ff4287fd486e24fb17b3deb2 Reviewed-by: Paul Wicking <paul.wicking@qt.io> Reviewed-by: Topi Reiniö <topi.reinio@qt.io> Reviewed-by: Qt CI Bot <qt_ci_bot@qt-project.org>
* Remove an end of para for deprecated commandThibaut Cuvelier2022-08-091-1/+0
| | | | | | | It was extraneous, as there is another ParaRight just after. Change-Id: Id107bd9db23665cd0bc4612e67dff370b1d64fa4 Reviewed-by: Paul Wicking <paul.wicking@qt.io>
* QDoc: Remove Node::setOutputFileName and Node::outputFileNameLuca Di Sera2022-07-221-23/+3
| | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | The `Node` class exposed a getter and a setter for an "outputFileName", which seems to represent the filename that a `Node` that generates a file in the output directory would have for that file. The setter was called in `Generator::beginSubPage`, where the documentation file was created during the generation phase, but the value that was set in the node was never accessed in other parts of the codebase. It is unclear what the exact purpose of the property was, supposedly some caching mechanism or a way to access a piece of data that was not easily accessible from other parts of the codebase. As the property was unused, it is now removed as dead code. Hence, all references to `Node::setOutputFileName`, `Node::outputFileName` and `m_ouputFileName`, the internal storage that `PageNodes` used for the property, are removed, together with their documentation, when present. `Generator::beginSubPage` delegated most of its work to `Generator::beginFilePage`, which took care of the actual file-creation logic, and differed from its agent only in that it stored the filename of the created file into the node that the file was created from. With `Node::setOutputFileName` being removed, `Generator::beginSubPage` is simply an alias to `Generator::beginFilePage` such that having both of them is not useful anymore. Hence, `Generator::beginSubPage` was removed in favor of `Generator::beginFilePage`. `Generator::beginFilePage` itself delegates much of the file-creation logic to `Generator::openSubPageFile` and, furthermore, more usages of `beginSubPage` and its associated method `endSubPage` were present in the documentation compared to the usages of `beginFilePage` and its associated method `endFilePage`. Hence, `Generator::beginFilePage` was renamed to `Generator::beginSubPage` and all usages references to `beginFilePage` were substituted with references to `Generator::beginSubPage`, such as to increase the consistency with the naming of `Generator::openSubPageFile` and to reduce the surface of the diff for the patch. `Generator::beginFilePage` had an associated method, `Generator::endFilePage`, an alias for `Generator::endSubPage`, that is now removed in favor of `Generator::endSubPage` as a consequence of the renaming of `Generator::beginFilePage`. A reference to the lack of storage of the created file name in the node was removed from the documentation of `Generator::beginFilePage`, now `Generator::beginSubPage`, as it was not relevant anymore. Change-Id: I6c9a6ef2db3bf4e1d176c6a2a134ba7dcae3cda5 Reviewed-by: Paul Wicking <paul.wicking@qt.io>
* qdoc: Introduce \modulestate commandTopi Reinio2022-07-151-1/+10
| | | | | | | | | | | | | | | | | | | | | | | | This command can be used in \module or \qmlmodule topic to describe a module state other than \preliminary or \deprecated. A typical use case is to mark modules in tech. preview: /*! \module QFoo \modulestate Techical Preview ... */ This information is displayed on the module page itself, as well as on the navigation bar of the module's member reference pages. Introduce a new function, QDocDatabase::getModuleNode() that retrieves the associated module node for any other Node instance. Use this in HtmlGenerator::generateNavigation() and also in Tree::resolveSince() to avoid code duplication. Fixes: QTBUG-104591 Change-Id: Ifd85e769f6df6f06ed9938da4f9981b22a56e19e Reviewed-by: Luca Di Sera <luca.disera@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-73/+99
| | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | 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>
* Rename QML basic types to value typesUlf Hermann2022-01-181-2/+2
| | | | | | | | | | | | | | Internally they've been called value types for a long time and they are not really basic. [ChangeLog][qdoc] QML value types are now marked with the \qmlvaluetype directive, rather than \qmlbasictype. \qmlbasictype still works but is deprecated. So far, all value types are hardcoded into the QML engine, making the directive irrelevant for user projects. This will change. Change-Id: I915ea0388e1de4c18911f7e81ba29559ebf33cb7 Reviewed-by: Kai Koehne <kai.koehne@qt.io> Reviewed-by: Andrei Golubev <andrei.golubev@qt.io>
* qdoc: Teach Config::getCanonicalPathList() to read include pathsTopi Reinio2021-10-081-1/+1
| | | | | | | | | | | | | | | | | | | | | Include paths must be canonicalized for them to be correct. Previously, the ClangCodeParser did this step, but it was done in relation to the current working directory (cwd), and at that point cwd is the directory of the main (top-level) qdocconf file - if includepaths variable was used in another included config file and contained relative paths, this produced incorrect results. As Config already knowns how to canonicalize paths, teach it to consider the common prefixes associated with include paths. As config variables store their location, we can produce absolute paths reliably in all situations. Document the includepaths and the associated moduleheader variables. Fixes: QTBUG-97034 Pick-to: 6.2 Change-Id: Iecf68e3cb09ced732f7a05270441da046e8df8d8 Reviewed-by: Paul Wicking <paul.wicking@qt.io>
* qdoc: Clean up index file generationTopi Reinio2021-07-011-18/+6
| | | | | | | | | | | | | | | | | | | | This is a continuation of the work started in commit 3e88b552. Stop adding a 'physical module name' for all nodes; this name is directly related to the \inmodule and \inqmlmodule commands, and is unnecessary for most node types. Enforce the module name only for classes, structs, unions, namespaces and header files. Drop redundant code, and stop writing module/group members to the index as unnecessary; they don't need to be read back in. Simplify example file name generation; base the filename always on the project name, example nodes typically never used the \inmodule command anyway. Pick-to: 6.2 Change-Id: I53a12b51f305cce28f5eb061d87ab11c61f54f6c Reviewed-by: Paul Wicking <paul.wicking@qt.io>
* QDoc: clean up html outputPaul Wicking2021-05-251-2/+2
| | | | | | | | | | | | | | | | | | Clean up some of QDoc's html output: * Remove erroneous <p/>. * Do not write empty <ul></ul> for lists that don't exist. * Do not generate links with missing href. * Drop duplicated anchors in tables. * Stop writing unnecessary and broken links to qml modules. * Don't duplicate <b>'s. * Change Atom type to Autolink for Q_INVOKABLE to not generate broken <a> tag if link target cannot be resolved. Task-number: QTBUG-81209 Task-number: QTBUG-73026 Fixes: QTBUG-93876 Change-Id: I4e9f01571263a21e0c25e5d8b3b7ff10fc18bea7 Reviewed-by: Topi Reiniö <topi.reinio@qt.io>
* QDoc: Code cleanupPaul Wicking2021-05-191-85/+87
| | | | | | | | | | | | | * 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>
* QDoc: Add guard for possible nullptr accessPaul Wicking2021-05-101-1/+1
| | | | | | | | Fix an assignment never read warning from Code Checker while at it. Change-Id: I5cb2475073dc04b43450dd81f4c243d075a96b9e Reviewed-by: Topi Reiniö <topi.reinio@qt.io>
* Doc: Improve \deprecated commandPaul Wicking2021-05-101-3/+6
| | | | | | | | | | | | | | | | | | | | | | 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>
* qdoc: Remove Node::Obsolete statusTopi Reinio2021-05-101-15/+5
| | | | | | | | | | | | | | | | | QDoc had two commands for the same purpose, \obsolete and \deprecated. As 'deprecated' describes the status better, as in, something that is subject to being removed from the public API, document only the latter. Keep \obsolete for now for backward compatibility. .index file recognize the "obsolete" attribute still for backward compatibility, converting to "deprecated". [ChangeLog][qdoc] Replaced \obsolete command in favor of \deprecated as it's a more accurate description of the intended status. Task-number: QTBUG-58249 Change-Id: I3d311ebf7b4a3e8a23fa85e4efcf60965cf12a13 Reviewed-by: Paul Wicking <paul.wicking@qt.io>
* QDoc: Code cleanupPaul Wicking2021-05-031-94/+23
| | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | * 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>
* Revert "QDoc: Add \deprecatedsince command"Paul Wicking2021-04-301-4/+1
| | | | | | | | | | | | This reverts commit 1637d91efd8fb389bc09bdaa960f5d9d4f9e0164. Reason for revert: User feedback shows this implementation isn't good enough. Further discussion led to the discovery of a better approach. Task-number: QTBUG-58249 Change-Id: I48e0500ac95745b1ce10a29e77c6fa515b9e048f Reviewed-by: Kai Koehne <kai.koehne@qt.io>
* QDoc: Add \deprecatedsince commandPaul Wicking2021-04-281-1/+4
| | | | | | | | | | | | | As deprecated methods may stick around over a couple of versions, add a command that lets us record which version something was deprecated in. [ChangeLog][qdoc] QDoc now lets you record the version something is deprecated in with the new \deprecatedsince command. Fixes: QTBUG-58249 Change-Id: I69de350502580f446008f717462bbc1c4c251564 Reviewed-by: Topi Reiniö <topi.reinio@qt.io>
* Revert "QDoc: Make Generator::fileBase static"Topi Reinio2021-04-151-2/+2
| | | | | | | | | | | | | | | | | | | | This reverts commit 3e67b5e4df84421b77f90cbf242abb4a3c4c93a5. The original implementation where fileBase() was a virtual function, overridden by HtmlGenerator, was needed as that generator is the only one that conditionally appends '-obsolete' to output file names. By using a shared static helper across all generators we broke that feature. Modify the revert to resolve conflicts and override fileBase() also for WebXMLGenerator; .webxml output should not refer to files with -obsolete suffix. Pick-to: 6.0 6.1 Fixes: QTBUG-92478 Change-Id: I7a7e3ef333724c96624569dd27b4812196931fb0 Reviewed-by: Paul Wicking <paul.wicking@qt.io>
* qdoc: Fix addendums for QML signals that contain '.' in the nameTopi Reinio2021-01-111-2/+3
| | | | | | | | | | QML signals may belong to a group, and the automatic note generation for corresponding signal handler must take this into account. Pick-to: 6.0 5.15 Fixes: QTBUG-85572 Change-Id: Ibfc793475618fb78a8ba0a0344537917ad6fb0bf Reviewed-by: Paul Wicking <paul.wicking@qt.io>
* qdoc: Fix linking to property groupsTopi Reinio2020-11-111-0/+4
| | | | | | | | | Only the members of a property group were written to .index, not the group itself; this made cross-module linking to the group fail. Fixes: QTBUG-88386 Change-Id: I096a2bbdd2b0af00c4d0e9a6974b6dc7dce075a2 Reviewed-by: Paul Wicking <paul.wicking@qt.io>
* qdoc: Unify generated documentation between \typedef and \typealiasTopi Reinio2020-11-091-27/+5
| | | | | | | | | | | | | | | | | | | | | | | | \typedef can be used as a substitute for \typealias for documenting aliases. Since they are identical in terms of usage, unify also the way they are documented: - Remove 'typedef' and '(alias)' from both the summary and details sections, making both appear as types. - Remove automatically generated 'This is a type alias for ...' note for type aliases. This typically resulted in duplicate statements. - Use '-typedef' anchor suffix for both. - Use 'typedef' as element for both in .index files and webxml output format. - Add template parameters for type aliases for DocBook generator; these were previously missing. Fixes: QTBUG-87622 Change-Id: I93986a2dc91c3c3dff9e21f5bf5cf19d0b55c4df Reviewed-by: Topi Reiniö <topi.reinio@qt.io>
* qdoc: Fix QList::removeAll() invocations to buildFriedemann Kleint2020-10-201-1/+1
| | | | | | | | After qtbase/3c74ba1f8b1052e684c67cbbb6f99eb4f7146f40, the type needs to be specified. Change-Id: Ic426e3088b14c9465d84acd760e35b9e87b0b231 Reviewed-by: Giuseppe D'Angelo <giuseppe.dangelo@kdab.com>
* qdoc: Stop removing content of the output directoryTopi Reinio2020-10-101-7/+8
| | | | | | | | | | | | | | QDoc deleted the contents of the directory specified by -outputdir in prepare phase - this was dangerous for users that do not expect that behavior. Instead of deleting, print out an error if the output directory is not empty. Fixes: QTBUG-87176 Change-Id: Iabefcc9733cf4c4b875fdd2bfd7f86f79d25349c Reviewed-by: Paul Wicking <paul.wicking@qt.io> Reviewed-by: Tor Arne Vestbø <tor.arne.vestbo@qt.io>
* qdoc: Report file overwrites as debug output instead of errorsTor Arne Vestbø2020-10-051-4/+5
| | | | | Change-Id: Ibf846f2ffb6eeccc7837e8ebb0e59db284436048 Reviewed-by: Paul Wicking <paul.wicking@qt.io>
* QDoc: Move separator into utilitiesPaul Wicking2020-10-051-7/+7
| | | | | | | | | Also remove some unused includes where I update includes in any case. Fixes: QTBUG-87081 Change-Id: Id63a3c58f9088a8f312468ff1ce0e8fd59f29de2 Reviewed-by: Topi Reiniö <topi.reinio@qt.io>
* qdoc: Manage logging category in utilities.h/cppTor Arne Vestbø2020-09-241-1/+0
| | | | | Change-Id: I39ec66fbe95edc42a3dac51e8bc718ee42cc4a2a Reviewed-by: Paul Wicking <paul.wicking@qt.io>
* qdoc: Add support for bindable propertiesTopi Reinio2020-09-211-0/+13
| | | | | | | | | | | | | | | | | Add support for the BINDABLE attribute in the Q_PROPERTY macro. The new properties are marked with 'bindable' tag, and the list of access functions/notifier signal is replaced with a descriptive note and a link to QProperty. Read-only properties are also properly marked as such. [ChangeLog][qdoc] The \property command now supports bindable C++ properties that use the new system based on QProperty. Task-number: QTBUG-85565 Change-Id: Ie352b3ce962b6b05a022d444da0991b8a849e474 Reviewed-by: Lars Knoll <lars.knoll@qt.io> Reviewed-by: Paul Wicking <paul.wicking@qt.io>
* QDoc: Make Generator::fileBase staticPaul Wicking2020-09-041-2/+2
| | | | | | Task-number: QTBUG-86390 Change-Id: I8de913513c7ab8ed0e77984b6023ec62b0cebd15 Reviewed-by: Topi Reiniö <topi.reinio@qt.io>
* QDoc: Remove unused methodPaul Wicking2020-09-041-13/+0
| | | | | | | We never call this from anywhere. Remove it. Change-Id: I24dad1d2b5df412d5aeed9c2ec2af76d8f26b5f3 Reviewed-by: Topi Reiniö <topi.reinio@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: Remove unused function used for debuggingTopi Reinio2020-06-171-15/+0
| | | | | | Task-number: QTBUG-71176 Change-Id: Iedcd7548857766da53087f9a41283a1331d3d0e0 Reviewed-by: Paul Wicking <paul.wicking@qt.io>
View Lorry Controller Status