summaryrefslogtreecommitdiffstats
path: root/tests/auto/qdoc/generatedoutput/expected_output/testqdoc-test.html
Commit message (Collapse)AuthorAgeFilesLines
* QDoc: Move tst_generatedoutput under srcLuca Di Sera2023-08-091-157/+0
| | | | | | | | | | | | | | | | | | | | | | | | | | QDoc is currently restructuring its source code to simplify certain expected future developments. As part of this restructuring, all tests have been moving from the "tests" directory to an appropriate place under the "src" directory. `tst_generatedoutput` performs end-to-end regression testing for the "qdoc" binary. It was previously positioned under the "test" directory and is now moved under the "src/qdoc/test" directory, as part of the restructuring. The "CMakeLists.txt" file under "src/qdoc/qdoc/test" was modified to dispatch to the moved "generatedoutput" test directory. The "CMakeLists.txt" file in "tests/auto/qdoc" was modified to include "src/qdoc/qdoc/tests/generatedoutput/CMakeLists.txt", to ensure that `tst_generatedoutput` is able to run in CI. Adds SPDX license headers to files that were missing it in "generatedoutput/testdata" Change-Id: I412496ef0bf8ea9c07deda63960c11f0a5a06cc4 Reviewed-by: Topi Reiniö <topi.reinio@qt.io>
* qdoc: Add meta description header to HTML outputTopi Reinio2023-03-061-0/+1
| | | | | | | | | | | | | | | | A meta description is an HTML element that provides a brief summary of a web page, typically displayed as part of a search engine results page. Use the \brief description for pages that have it. This should cover virtually all of the API reference as type \brief appears on module pages and therefore is rarely missing. Many overview \page's have it as well. Pick-to: 5.15 6.2 6.4 6.5 Fixes: QTBUG-111360 Change-Id: Ie403777fd895a995bbd7d717333e95c1b6b77d89 Reviewed-by: Kai Köhne <kai.koehne@qt.io>
* QDoc: Tag C++ elements as "noexcept" when they are marked as suchLuca Di Sera2023-01-251-2/+2
| | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | 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: Append translate attribute to few more blocksVenugopal Shivashankar2022-11-291-20/+20
| | | | | | | | | | | | - Auto links - Qml property summary and method signature - Anchors - See also entries - All C++ classes and QML types list Task-number: QTBUG-106679 Change-Id: Ib7046321ccac16bf1141885a5cf2d411084f57ab Reviewed-by: Topi Reiniö <topi.reinio@qt.io>
* qdoc: Add translate attribute to HTML blocksVenugopal Shivashankar2022-11-181-32/+32
| | | | | | | | | | | | | | A browser translates everything by default, which means even the <code>, <pre>, <table>s listing the class members, and so on, are also translated. With this change, such HTML blocks will include the "translate=no" attribute, indicating that they should not be translated. Pick-to: 6.4 6.2 5.15 Fixes: QTBUG-106679 Done-with: Topi Reinio <topi.reinio@qt.io> Change-Id: I446fe26c73b9e3fee2984297bd504ae72c555e73 Reviewed-by: Topi Reiniö <topi.reinio@qt.io>
* qdoc: Stop listing invalid group names in type referenceTopi Reinio2022-11-021-1/+1
| | | | | | | | | | | | | | | | QDoc was listing links to groups that a C++ class or QML type documentation topic was part of - that is, all group names that appeared as arguments to \ingroup command(s). However, not all group names used in Qt docs have a matching \group topic. This resulted in listing of groups that do not have a title and/or are not valid as link targets. Filter out the list of group names into CollectionNode pointers for groups that have been 'seen', which means that they do generate a group page and can be linked to. Fixes: QTBUG-108100 Change-Id: I2924d49d7bc9947fd4ac12c6f1c0daed96d52da6 Reviewed-by: Luca Di Sera <luca.disera@qt.io>
* QDoc: Fix ordering of detailed members/all members sectionLuca Di Sera2022-09-291-5/+5
| | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | QDoc organizes the way in which certain list of elements of the documentation are ordered when rendered through an internal structure, `Sections`, that, given an `Aggregate`, an internal representation of a documentable element that is composed of multiple documentable elements, partitions the member of the `Aggregates` into multiple ordered sets that dictate the order of the elements in the output documentation. Internally, `Sections` contains an associate structure, `Section`, that exposes a series of maps ordered based on the ordering relation defined by the free-function `sortName` in "sections.cpp". `sortName`, produces an orderable string based on the name of a certain element and its properties. For example, for elements that are constructors it produces a string that is alphabetically ordered before the one that it produces for elements that are destructors. In particular, `sortName` produces a string that is composed of a prefix letter, dictating the order for the class of documentable element. Furthermore, it produces a suffix for overloads, to ensure that they are ordered based on their overload number. If the element has no "particular" property, a general prefix that precedes almost any other element is used. For example, `sortName` was supposed to order the list of functions in a class with the order constructors, destructors, everything else that is not an operator, operators. To support this ordering the prefixes "C", "D", "E" and "F" were used respectively, so that a constructor X would produce a sortable string "CX", a destructor X would produce the sortable string "DX" and so on. For overloads, a number would be added as a suffix, such that, given two function X and Y that are overloads, that is they have the same name N, the produced name would be, for example, "EN" and "EN 1", further producing an internal order for equivalently named elements. The number that is used in this case is the "overload number" of a function. When QDoc encounters a series of overloads, it stores them into a linked list, to relate them. Furthermore, one of the overload is chosen as a "primary overload", acting as the head of the list and as the target candidate to resolve an ambiguous link to an overloaded function. All elements of a linked list of overloads are given a number. The "primary overload" is given the number 0, the next overload in the list, generally depending on the order in which QDoc encounters the documentation for the overloaded elements, is given the number 1 and so on. Nonetheless, the code for `sortName`, was incorrectly implemented, so that the produced string was not able to take into account certain properties of some C++ documentable elements, such as the element being a constructor or a destructor, instead producing a general ordered string that partitioned them with other non ordered elements. The bug was due to an incorrectly implemented branch condition. `sortName` would branch on a function to check if it is a constructor, destructor or operator only if the function was marked as a "cpp function", as per `FunctionNode::isCppFunction`. A `FunctionNode`, the internal representation for documentable elements that are C++ functions, signal, slots, variables or QML methods, signals or signal handlers, is marked with a "metaness", that decides the "kind" of element that the `FunctionNode` instance represents. For example, a `FunctionNode` instance that represents a QML method would have a metaness of `QmlMethod`, while a `FunctionNode` instance that represents a constructor would have a metaness of `Ctor`. The `isCppFunction` method specifically checks that a `FunctionNode` instance has a metaness of "Plain", which is the metaness that `FunctionNode` that are non-QML, non-signal, non-slot, non-constructor, non-destructor, non-macro, non-assignment-operator have. As a constructor, destructor, signal, slot and assignment-operator would have a different metaness, the code that specifically handled those cases was never reached, such that the produced string for those elements was the fallback one, simply producing a prefix of "B" followed by the node name. This in turn ordered them in a mixed way, such that, for example, instead of having constructors being followed by destructors, the generated documentation would position other elements in-between. Furthermore, as the correct branches were never taken, the overload number for overloaded constructors, destructors, signal, slots and assignment-operators would not be added as a suffix, resulting in an internal order that varied depending on the internal structure and sorting algorithm used to sort the elements of a `Section`. In our specific case, `Section` uses a `QMultiMap`. As the overload number was not taken into account, overloads would be stored under the same key, and generally appear in reverse order, such that "X1", "X2", "X3" would be ordered as "X3", "X2", "X1". To solve the issue, the code was reorganized so that the expected sortable string was produced for the afflicted elements and the overload number would be taken into account when relevant. This is done by removing the incorrect condition, instead conditioning the code based on the inspected element being a `FunctionNode` that comes from C++ code. With the change, the following ordering problems are resolved in the documentation: - In the detailed members section of a C++ class, constructors and destructors were not ordered one after the other, possibly having other members in between. For example, the documentation for `QObject` would show the only available constructor, followed by the `deleteLater`, `objectNameChanged` and `destroyed`slot and signals, followed by the destructor. With the change, the constructor will be followed by the destructor and then by all other elements. - Overloaded elements that are constructors, destructors, slots, signals and assignment operators were ordered in the opposite order that QDoc ascribes to them. For example, in `QAxObject` the constructors would be ordered as "constructor with arity-2 and IUnknown first parameter", "constructor with arity-2 and QString parameter", "constructor with arity-1", while QDoc consider those overloads in the opposite order. With the change, they are now ordered as QDoc orders them. Do note that the order that QDoc uses depends mainly on the order in which the elements are documented in the code, meaning that if there is a lack of consistency in the order in which the constructor are documented, there will be a lack of consistency in their order in the documentation. Generally, it seems that lower-arity overloads are documented before their higher-arity counterparts, providing for an easier to read order. Nonetheless, in the future this might change so that QDoc actively orders overload based on some of their properties, such that the current ordering should not be relied upon. - Certain non-constructor, non-destructor, non-operator elements in the detailed members section of a C++ class were not ordered alphabetically. In particular, slot and signals. For example, `QObject` would position the `deleteLater`, `objectNameChanged` and `destroyed`slot and signals at the top of the list, between the constructor and destructor. With the change, those kind of members will be positioned with all other non-constructor, non-destructor and non-operator members, positioned based on their alphabetical order. - All instances of an assignment operator in the detailed members section of a C++ class were ordered at the top of the list of elements, together with constructor, destructors, signal and slots. For example, in the documentation for `QString` they would appear between the constructors and destructor. With the change they are now correctly positioned at the end of the list with all other operators. All of the above changes have the same effect on the ordering of the all members file of a C++ class. The regression-files for `tst_generatedOutput` were regenerated to take into account the changes, as they were generally afflicted by the incorrect positioning of the assignment operators. Change-Id: Ia7e3897b8c33aca0a753ddc73bdd79a962e73746 Reviewed-by: Topi Reiniö <topi.reinio@qt.io>
* doc: Handle macros while generating since infoVenugopal Shivashankar2022-08-221-1/+1
| | | | | | | | | | | | | 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>
* QDoc: Add support for en-dash and em-dashPaul Wicking2022-08-181-0/+22
| | | | | | | | | | | | | | | | | | | | | | | | | | | | This patch modifies the DocParser such that QDoc will now treat two consecutive hyphen characters (--) as markup that outputs an en dash character, and three hyphens (---) as markup for an em dash. As the rules governing use of en dashes and em dashes are defined by style guides and not grammar, QDoc is left generally permissive of their use. However, code blocks and content that is monospaced (passed to the \c-command), must be left untouched, as otherwise, errors, such as the mangling of the decrement operator in code snippets, could occur. Also ensure that the HTML QDoc generates uses the correct HTML entity codes. Of course, not feature of QDoc is complete without documentation. Even though it strictly speaking isn't a command, due to the organization of content in the QDoc manual, add documentation for en dash and em dash sequences to the markup command section. [ChangeLog][QDoc][QDoc now interprets -- as en dash, and --- as em dash.] Fixes: QTBUG-105729 Change-Id: I2b6d547dcd9d8b4f1d9348f2596c7b0abc28d039 Reviewed-by: Luca Di Sera <luca.disera@qt.io> Reviewed-by: Topi Reiniö <topi.reinio@qt.io>
* qdoc: Make types inherit \since statement from their module docsTopi Reinio2022-07-131-0/+1
| | | | | | | | | | | | | | | When introducing a new module (C++ or QML) documentation, the \module or \qmlmodule topic should be marked with a \since command. Types belonging to the module will then inherit the \since by default, unless explicitly specified in the type documentation. Unify the interface of a similar Tree::resolveUsingClauses() method to explicitly require a reference to an Aggregate for the recursive operation. Fixes: QTBUG-104613 Change-Id: I48afe82e55a889dab43d8c59882c52d44b8bb69a Reviewed-by: Luca Di Sera <luca.disera@qt.io>
* QDoc: Assume that aggregates have a single meaningful include fileLuca Di Sera2022-07-081-4/+7
| | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | QDoc's `Aggregates`, which are used to internally represent "containing" elements, such as cpp classes, have a concept of "include files". "include files" represent the name of a file or similar construct from which the aggregate can be obtained the sources. For example, the name an header file declaring a cpp class. Aggregates, up to now, exposed an interface that allowed to set multiple "include file" for each aggregate. Furthermore, QDoc allows the user to manually specify include files through the use of the "\inheaderfile" command. Those include files were later used by QDoc to show information about the aggregate, In particular, the generator would show an "include requisite" to help a user understand where to import the aggregate from. The multiplicity of the include files had effects on later parts of the code that either set or read them. For example, the generators whose code required handling the multiplicity to show the required information on multiple lines. In practice, this never took effect as, at least in Qt's codebase, no aggregate has more than 1 include file. While it is not unthinkable of wanting to have more than one include file, we consider improbable for it to happen. In general, include file will mostly be used for classes, which we expect to be able to be meaningfully included from a specific file only. As such, the interface for `Aggregates` is now modified to expose a single include file per aggregate. The previous methods were removed and a singular version of them was introduced. The internal state of `Aggregate` was modified to take this into account storing a single optional include file instead of a vector of them. A singular include file was set during the construction of `HeaderNode`. The constructor is now modified to use the new interface. Include files are then generally set only during the code parsing phase. In particular, each file-name coming from an "\inheaderfile" command was appended to the vector of include files. Furthermore, each aggregate either inherited the include files of one of its parent or generated one from the aggregate's name when no sensible parent was available, unless a previous "\inheaderfile" command for the aggregate was encountered. The code is now changed to take into account the lack of multiplicity. The semantic is mostly preserved from the previous version and, in the case of the Qt's codebase, is preserved entirely due to no aggregate with more than one include file ever being produced. Some slight semantic breakages are, albeit, included with this change. Previously, if the user provided more than one "\inheaderfile" command, the arguments from all of them would be preserved and saved in the relevant aggregate. With the current change, each "\inheaderfile" after the first will overwrite the preceding value, such that only the last encountered command will be taken, effectively, into account. This breakage would currently be opaque for the user. It is later advised to better expose this behavior through changes to `DocParser`, albeit those changes are not expected to be performed right away as a more thorough inspection of `DocParser` must be made in general. Furthermore, the previous version would set include files that could be the empty string, specifically as they came from an "\inheaderfile" command. The new version ignore empty include files, such that it is ensured that, if an include file was ever provided, that include file is not an empty string. This breakage improves on the previous version, where later user of the include files had to perform possibly costly filtering operations to avoid empty strings, who are expected to have no meaning as an include file. To better support this change and partially help in exposing this semantic, the new interface for the include file exposes an std::optional and informally guarantees, but does not enforce, that if a value is ever set it is not the empty string. The changes to the code were made so as to ensure that this will be the case as for the current codebase. A more thorough enforcement was avoided as it would require deeper changes that are currently unfeasible. User of the include file, namely the generators, were modified to take into account the lack of multiplicity. The generators previously depended on `CodeMarker::markedUpIncludes` to flatten the vector of include files into a representable string. `CodeMarker::markedUpIncludes` is now supplanted with `CodeMarker::markedUpInclude`, its singular version, to take into account the lack of multiplicity. The semantics of the method is preserved and is expected to be equivalent to a call to `CodeMarker::markedUpIncludes` for vectors of include files with a single element, with the exclusion of a trailing newline. Small clean up changes were made to `HtmlGenerator::addIncludeFilesToMap`, which is the main consumer of include file for the HTML format. The method was renamed to its singular version. Some now unnecessary operations, such as the filtering of include files that were the empty string, are now removed. The `text` parameter of the method, previously a `Text*`, is now modified to a reference. The `Text` that is passed to the method is always created in its immediate scope and is never a nullptr, allowing us to remove and unnecessary check. Indeed, calling the method with a nullptr would generally be a no-op, such that there would be no meaning to it in the first place (and there was no flow-requirement for it to be a no-op). A slight change to the laying out of the table in `HtmlGenerator::generateTheTable` was included to better divide the lines of the table. The regression files for `tst_generatedOutput` were regenerated to take into account the additional newlines in the tables. Change-Id: Idebca8a74444328cd21c83be9e3f3b1706907f84 Reviewed-by: Topi Reiniö <topi.reinio@qt.io>
* QDoc: Add reference to groups in class/qmltype pagesLuca Di Sera2022-06-231-0/+1
| | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | QDoc allows to group related elements through the use of the "\ingroup" command. Furthermore, it allows the generation of a page for a certain group, through the "\group" command, to provide information about the way that the elements are related and a list with links to element that are member of the given group. While there is an obvious connection from the page of a group to its elements, there currently is no such inverse connection, reducing the discoverability of those pages for the user of the documentation. To reduce this issue, a line providing links to the available pages of groups that a class or qmltype element is a child of is now added to respective element pages. QDoc allows to include an element into some group without generating a page for the group. In particular, this allows the addition of elements that are defined in a certain project in groups whose page is defined in a different project. To support the cross-project linking that those cases require, some changes were made to the way in which QDoc finds source-of-truth information for a group node. QDoc stores a group every time an "\ingroup" command is found. When a "\group" command is found, the stored group is enhanced with the provided information. If the "\group" command for a certain group is not in the same project as some of its "\ingroup" declaration, the information about the group must be read from an index file. When this is done, assuming that the correct dependency are declared in the configuration file, QDoc ends up with multiple representation for the same group, only one of which, assuming that no repeated declaration for the same group exists, which is assumed to be how group are implicitly supposed to work, albeit this might not be enforced, contains complete information, which are required for linking. Generally, if the group is defined in a depended upon module, the directly accessible group representation, the one on the primary tree, will not contain complete information, inhibiting linking. QDoc further processes those group representation, generally for the one on the primary tree, merging them with the information from the other representations of the same group that were read from the index files, to ensure that a correct list of members, containing the members that are declared in other projects, is generated. To ensure that correct linking information are available as long as a group definition exists, either in the current project or one of its dependencies, this merging procedure was modified to merge any information that is required for linking purposes, so that it is available in the directly accessible representation of the group. As this merging procedure is performed when needed, such that it must be performed each time a group is accessed for information, as it might not have been merged before, a possibly high overhead might be generated when the group is accessed many times. For this feature in particular, access to the group is required for each class and qmltype pages, increasing the amount of expected merges. To lessen the impact that this would have on performance, a hackish caching was added to the merging procedure, to avoid merging more than once. The merging procedure is only called during the generation phase and is only meaningful when some representation of a group was generated from an index file. As the index files are always read much before the generation phase and the primary group representation itself is not expected to change during the same phase, the result of a merge should be the same at any point in the generation, such that the cache should never invalidate and no precautions for cache invalidation were provided. The regression files for `tst_generatedOutput` were regenerated to take the changes into account. Fixes: QTBUG-104237 Change-Id: Ia2332a7b91f7d16c16899c2de9920175bc57f177 Reviewed-by: Topi Reiniö <topi.reinio@qt.io> Reviewed-by: Kai Koehne <kai.koehne@qt.io>
* qdoc: Improve generated navigation bar for C++ and QML typesTopi Reinio2022-04-281-0/+1
| | | | | | | | | | | | | | | | | | | QDoc included only the page(s) provided in navigation.cppclassespage and navigation.qmltypespage in the navigation bar (breadcrumbs) generated for type reference pages. If a type is part of some other (sub-)module, include a link to that module specifically after the generic 'C++ Classes' or 'QML Types' link. In passing, fix an issue where QML type pages lost an entry for *this* page on the navigation bar if the navigation config variable was not set. Pick-to: 6.2 6.3 Fixes: QTBUG-102387 Change-Id: I1316082858455938e4f4e2173f527b87c9a78f08 Reviewed-by: Luca Di Sera <luca.disera@qt.io>
* Use find_package(Qt6 REQUIRED COMPONENTS ...) idiomKai Köhne2022-03-181-1/+1
| | | | | | Pick-to: 6.3 Change-Id: Ie7c581f75e3539ce431178f5d9fb7cdff252caed Reviewed-by: Jörg Bornemann <joerg.bornemann@qt.io>
* QDoc: clean up html outputPaul Wicking2021-05-251-1/+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>
* Doc: Improve \deprecated commandPaul Wicking2021-05-101-1/+1
| | | | | | | | | | | | | | | | | | | | | | 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>
* Revert "QDoc: Add \deprecatedsince command"Paul Wicking2021-04-301-6/+0
| | | | | | | | | | | | 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-0/+6
| | | | | | | | | | | | | 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>
* QDoc: Stop writing <a name=> html tagsPaul Wicking2021-04-261-18/+12
| | | | | | | Task-number: QTBUG-73026 Task-number: QTBUG-81209 Change-Id: I47d0fd94141d631abd8ea709c7ef0dc311312375 Reviewed-by: Topi Reiniö <topi.reinio@qt.io>
* Doc: Use PRIVATE linkage with target_link_librariesKai Koehne2020-11-301-1/+1
| | | | | | | | | | | | Fix the CMake snippet in the class documentation pages to use PRIVATE linkage. PUBLIC linkage is only needed if the Qt types are also used in the public API of the user's module. Task-number: QTBUG-88935 Change-Id: If4aee64a25ec8152a2a0ad5b5504f53a41d93079 Reviewed-by: Paul Wicking <paul.wicking@qt.io> (cherry picked from commit a774889df6ee2e07d0f01580bc9e486365200ff5) Reviewed-by: Qt Cherry-pick Bot <cherrypick_bot@qt-project.org>
* qdoc: Fix CMake statementKai Koehne2020-11-271-2/+2
| | | | | | | | | | | | find_package() only knows about COMPONENTS, not COMPONENT. While at it, also make the find_package call REQUIRED, and do use the versioned library target name. Change-Id: I1410b7c8cce84a1f24853bfcef650e440c468b33 Reviewed-by: Paul Wicking <paul.wicking@qt.io> (cherry picked from commit c57c4836d627406f33b80e4a188c93f79331a1bc) Reviewed-by: Qt Cherry-pick Bot <cherrypick_bot@qt-project.org>
* qdoc: Unify generated documentation between \typedef and \typealiasTopi Reinio2020-11-091-2/+2
| | | | | | | | | | | | | | | | | | | | | | | | \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 handling of \fn signatures with unnamed parametersTopi Reinio2020-10-271-3/+3
| | | | | | | | | | | | | | | | A misplaced 'i++' caused an error where names of documented parameters were shifted around if one or more of the parameters were unnamed. Fixing the above uncovered issues with handling of \fn commands with [tag] argument; improve and simplify related code. Finally, avoid redundant space characters when generating signatures with unnamed parameters or in 'All Members' page where parameter names are omitted. Fixes: QTBUG-87855 Change-Id: I526c89c10c66572b8c71106660f43346a4751e4e Reviewed-by: Paul Wicking <paul.wicking@qt.io>
* qdoc: Allow documenting implicitly generated special member functionsTopi Reinio2020-10-161-0/+10
| | | | | | | | | | | | | | | | | Implicitly generated class members such as default constructor are not visible in the Clang AST, and QDoc failed to match \fn commands for such functions. Fix this by visiting the translation unit generated for the \fn command, and constructing a temporary FunctionNode. If this temporary node is of any of the special member types that can be implicit, add that function as a child to the class node. Add 'default' attribute for such functions in the generated docs. Fixes: QTBUG-86984 Change-Id: I6c662e4ca030d80b68dd22f3639526093c27c20b Reviewed-by: Paul Wicking <paul.wicking@qt.io>
* qdoc: Document friend functions as related non-membersTopi Reinio2020-10-081-0/+13
| | | | | | | | | | | | | | | | | | When parsing a friend declaration in a class, QDoc associated the subsequent function declarations to the namespace scope. This was conceptually correct as friend functions are not class members, but made it impossible to match documentation to these functions using the \fn command; the functions are still found under the class scope in Clang AST, and this has to align with QDoc's node tree for the documentation to be matched correctly. Fix this by letting friend functions remain in the class, keeping track of the friend declarations, and marking friend functions automatically as related non-members. Fixes: QTBUG-86987 Change-Id: I0ad26eed1c72af9302c9e420f5db0ec98c40d86a Reviewed-by: Paul Wicking <paul.wicking@qt.io>
* qdoc: Test documentation for a macro parameter with a reference typeTopi Reinio2020-09-261-3/+3
| | | | | | Task-number: QTBUG-86010 Change-Id: Ibc70cb2ecf4233b84c4043684e8487d9fe7a7f89 Reviewed-by: Paul Wicking <paul.wicking@qt.io>
* qdoc: Ignore unnamed declarations when retrieving parameter namesTopi Reinio2020-06-301-0/+5
| | | | | | | | | | | | | The Clang visitor returns a CXCursor_ParmDecl also for parameter declarations in the return type, as is the case with std::function wrappers that take parameters. Handling these caused us to omit some of the actual parameter names. Skip declarations that do not provide a parameter name. Fixes: QTBUG-67244 Change-Id: Id5d8d3302fe3580c10814735a0684b83b8d5ebb4 Reviewed-by: Paul Wicking <paul.wicking@qt.io>
* qdoc: Extend synopsis for detailed reference sectionsTopi Reinio2020-06-081-3/+2
| | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | Include \since information for detailed synopsis generation, and allow duplication of qdoc comments for C++/QML nodes on the condition that the extra comments contain no body text, only meta-commands. The use case is to have full status information in the signature/section title, and allow additional meta-commands for items that share a documentation comment. /*! \fn void A:foo() \fn void A:foo(int i) Shared documentation for overloads. */ /*! \fn void A:foo(int i) \since 2.0 */ Extract the code for 'extra' synopsis into a new helper function and use for both HTML and DocBook generators. Fixes: QTBUG-55739 Fixes: QTBUG-82902 Change-Id: I6e797d3ce7bc7b02102bb949515f88e7a0fbe929 Reviewed-by: Topi Reiniö <topi.reinio@qt.io>
* Merge remote-tracking branch 'origin/5.15' into devTopi Reinio2020-05-291-2/+15
|\ | | | | | | Change-Id: I8c1fc05462e1b99b16d52e4f43b2b4b1aa645152
| * qdoc: properly implement \typealias commandTopi Reinio2020-04-231-0/+13
| | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | \typealias was already a command recognized by QDoc, but it was simply treated as a synonym for \typedef and was not documented. Implement proper support for the command: - Add [alias] designation both in type summary and details. - Auto-generate information about the aliased type, including a link if aliasing a public, documented type. - Auto-convert aliases documented with \typedef to type aliases. - Add basic support for aliases also to DocBook and WebXML generators. - Document \typealias. Fixes: QTBUG-82712 Change-Id: Iafa8c7def0a7488d7521fbc2862290a9bb3167ff Reviewed-by: Qt CI Bot <qt_ci_bot@qt-project.org> Reviewed-by: Paul Wicking <paul.wicking@qt.io>
| * qdoc: Fix handling of default values for function parametersTopi Reinio2020-04-211-2/+2
| | | | | | | | | | | | | | | | | | | | | | | | | | | | | | When using an \fn command to document a function that has default values for parameter(s), The Clang parser retrieves a relevant section of the source file that contains the expression for the default value. In case of \fn, the source is a temporary translation unit that was constructed on the fly - but it may not exist anymore, and the default value is lost. Fix this by storing the contents of the temporary TU for later access. Fixes: QTBUG-83472 Change-Id: I20ad9e3322636450db1def65933837c1c767f2c4 Reviewed-by: Paul Wicking <paul.wicking@qt.io>
* | QDoc: Add CMake package information to documentationPaul Wicking2020-05-261-1/+2
|/ | | | | | | | | | | | | | | | | | | | | | This introduces a new command to QDoc, \qtcmakepackage. The command works exactly like the \qtvariable command. The command adds a table row in class and namespace documentation pages. This entry contains CMake: find_package(Qt6 COMPONENT Foo) target_link_libraries(mytarget PUBLIC Qt::Foo) ...immediately preceding the existing "qmake: += Foo" row. [ChangeLog][qdoc] Added a new QDoc command, \qtcmakepackage, that adds CMake snippets to class and namespace documentation. Fixes: QTBUG-84024 Pick-to: 5.15 Change-Id: I687813c76d92f20ec1eac6229ca2c5ef22ca3591 Reviewed-by: Topi Reiniö <topi.reinio@qt.io> Reviewed-by: Thibaut Cuvelier <cuvelier.thibaut@gmail.com>
* QDoc: Use correct node type string for \since in shared commentsPaul Wicking2020-03-061-0/+1
| | | | | | | | | | | | | | | | | Shared comment nodes were not handled as a special case when generating "This [class/function/method/type/etc] was introduced in" strings when QDoc encountered a \since command. These ended up with the default value, "documentation", which led to unexpected text in the documentation. * Add handling of shared comment nodes and get the node type from the first node in the collective. * Amend generated output test to cover this scenario. Fixes: QTBUG-82534 Change-Id: I444e95e0214f312649ec2720c23c98e698402abf Reviewed-by: Kai Koehne <kai.koehne@qt.io> Reviewed-by: Topi Reiniö <topi.reinio@qt.io>
* qdoc: Teach QDoc to output function and class template parametersTopi Reinio2020-01-201-1/+1
| | | | | | | | | | | | | | | | | | | Add a visitor functor that reconstructs template parameters from the Clang AST, and use it when either a class or a method template is detected. Store this information in the node - for now, they are used only in the class reference page subtitle (for classes), and detailed section of function documentation. Template parameters are not considered when searching/linking to entities, they are for display only. [ChangeLog][qdoc] Added capability to display class/method template parameters in the generated documentation. Fixes: QTBUG-17456 Change-Id: I300cc63b9fa20d4f6efaeaa27ea3769635a7b32c Reviewed-by: Topi Reiniö <topi.reinio@qt.io>
* QDoc: Use html5 charset declarationPaul Wicking2020-01-051-1/+1
| | | | | | | | | | | | As we claim the html is html5 compliant (<!doctype html>), use the html5 charset declaration instead of html 4.01 style. Also, drop the trailing '/' (no need to close meta element). Update all test content to match the new output. Task-number: QTBUG-73026 Change-Id: I4cf58a342a2bfb9e76245bd3fb91525e6e59f622 Reviewed-by: Topi Reiniö <topi.reinio@qt.io>
* QDoc: Drop xml prolog from html outputPaul Wicking2020-01-051-1/+0
| | | | | | | | | | The html output is not well-formed xml, so let's not claim that it is. Update expected output in tests to reflect the change in output. Task-number: QTBUG-73026 Change-Id: I0e6646eb33cafad7be543869585609d6f4cb0fdb Reviewed-by: Topi Reiniö <topi.reinio@qt.io>
* qdoc: Fix regression in C++ functions sharing a documentation commentTopi Reinio2020-01-051-0/+12
| | | | | | | | | | | | | After a recent refactoring, the function that distributes c++ documentation nodes failed to do anything with a function node that was sharing a comment with other nodes. Fix the issue and add a testcase for shared c++ \fn documentation comments. Fixes: QTBUG-81005 Change-Id: I6320bab232671f8cd969a37136708fc172de8409 Reviewed-by: Paul Wicking <paul.wicking@qt.io>
* Factor out the formatting of the "since" textThibaut Cuvelier2019-12-131-1/+1
| | | | | | Change-Id: I3ec3342eb3362664c605c4120238566d87c8b176 Reviewed-by: Paul Wicking <paul.wicking@qt.io> Reviewed-by: Topi Reiniö <topi.reinio@qt.io>
* Add new input data to test \reimp commandLevon Sargsyan2019-10-141-1/+7
| | | | | | | | | | | | The purpose of this change is to test the documentation that is generated for comments that use QDoc's \reimp command. This is done by adding a new virtual method to the Test class, and a new inherited class that implements it. Change-Id: If2367362475cc3daf31004dec43e8e15076acfb5 Reviewed-by: Levon Sargsyan <levon.sargsyan@qt.io> Reviewed-by: Topi Reiniö <topi.reinio@qt.io> Reviewed-by: Paul Wicking <paul.wicking@qt.io>
* Add new test data for htmlFromCpp test-pointLevon Sargsyan2019-10-031-1/+7
| | | | | | | | | | | | | This change introduces several data updates for the test htmlFromCpp, that will help us prevent possible regressions in the future. Enhancements include: 1. CPP function with default arguments. 2. Usage of \qtvariable to produce appropriate qmake instructions. 3. Obsolete and deprecated members. Change-Id: I9e1d346b43f515f649004d180d1ddead67df97b4 Reviewed-by: Paul Wicking <paul.wicking@qt.io>
* qdoc: generatedoutput autotest: Test more C++ -related commandsTopi Reinio2019-09-301-0/+14
| | | | | | | | | | | | | | | Improve the coverage of C++ test with the following cases: * \macro taking an argument * A non-related member (above macro) associated with a class * \inheaderfile command * \since command Fix incorrect expected output since fixing the bug mentioned in the task number. Task-number: QTBUG-77960 Change-Id: I6010cab9ab0a86a1897a38a397b8d7ba8155f95a Reviewed-by: Paul Wicking <paul.wicking@qt.io>
* Add an initial test case for C++ documentation generated by QDocTopi Reinio2019-09-051-0/+54
This will be expanded later on. The minimal C++ project tests QDoc's HTML output for a module page, namespace and class reference, and some class members. Change-Id: Ifabc394116b675152d3ac95dc96a46e6e9c768ec Reviewed-by: Paul Wicking <paul.wicking@qt.io>
generated by cgit v1.2.3 (git 2.25.1) at 2024-06-03 16:48:38 +0000