summaryrefslogtreecommitdiff
path: root/src/qdoc/doc
Commit message (Collapse)AuthorAgeFilesLines
* QDoc: Move QDoc source files under a further "qdoc" directoryLuca Di Sera2023-04-1237-12146/+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: Fix links in \generatelist <groupname> outputTopi Reinio2023-04-111-2/+8
| | | | | | | | | | | | | | | | | | The \generatelist command already supported listing members of a group as a simple unordered list of titles/links, but the links were broken as they always referred to the current document. In DocBook generator, reuse generateAnnotatedList() for this purpose as it already has support for outputting simple itemized/unordered lists. Create a new private enum GeneratedListType to select the list 'subtype' and clean up the API. Add simple test case and documentation of the new argument. Fixes: QTBUG-111575 Pick-to: 6.5 Change-Id: I30e4976cef3b6aa5414aac457844ae5bc0762f3d Reviewed-by: Paul Wicking <paul.wicking@qt.io>
* Revert "qdoc: Add support for 'category' argument in \generatelist command"Topi Reinio2023-04-111-29/+2
| | | | | | | | | | | | | | | This reverts commit df735050ecd01687f17df8f161c706541319ad05. While the commit works, it introduces unnecessary complexity to the processing of the \meta command. The same functionality can be achieved with the help of a documentation macro. The commit did contain a bug-fix for the \generatelist command, which is re-introduced as a separate change. Pick-to: 6.5 Change-Id: Ie8578baa35cfee210fc52428c610307f51103d22 Reviewed-by: Paul Wicking <paul.wicking@qt.io>
* Update Qt logosFriedemann Kleint2023-03-281-0/+0
| | | | | | | | As a drive-by, add a 128x128 logo for Designer, as screen sizes grow. Pick-to: 6.5 Change-Id: I886841c9a6cbc8b6996466d9ca687be6f7eca666 Reviewed-by: Alessandro Portale <alessandro.portale@qt.io>
* qdoc: Add support for 'category' argument in \generatelist commandTopi Reinio2023-03-271-2/+29
| | | | | | | | | | | | | | | | | | | | | | | | | | | | | Examples in the Qt codebase are now tagged with specific categories, using the '\meta category {Category}' command. To easily generate lists of members in each category, add support for a 'category' argument in the \generatelist command. Internally, utilize the mechanism already provided by \ingroup command, by adding the node to an internal group prefixed by 'category', when processing the '\meta category' command. \generatelist already supported listing members of a group as a simple unordered list of titles/links. Fix the generated links as they were broken, always referring to the current document. In DocBook generator, reuse generateAnnotatedList() as it already has support for outputting simple itemized/unordered lists. Create a new private enum GeneratedListType to select the list 'subtype' and clean up the API. Add simple test case and documentation of the new argument. Pick-to: 6.5 Fixes: QTBUG-111891 Fixes: QTBUG-111575 Change-Id: Icd5647a09b9ae8cb0ac243fa49d3d99263d397cb Reviewed-by: Paul Wicking <paul.wicking@qt.io> Reviewed-by: Nicholas Bennett <nicholas.bennett@qt.io>
* qdoc: Warn about documented global functions that generate no docsTopi Reinio2023-03-241-0/+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>
* Doc: QDoc Manual: Mention \inlineimage in \value documentationTopi Reinio2023-03-211-0/+3
| | | | | | | | | Pick-to: 6.5 Fixes: QTBUG-111310 Change-Id: Ib8515535181cec75140cb5f065cd3f5aa45ee16c Reviewed-by: <safiyyah.moosa@qt.io> Reviewed-by: Shawn Rutledge <shawn.rutledge@qt.io> Reviewed-by: Venugopal Shivashankar <Venugopal.Shivashankar@qt.io>
* qdoc: Allow \meta tags {...}Kai Köhne2023-03-201-2/+3
| | | | | | | | | | | | | So far we only supported \meta tag {}, even for multiple tags. This is confusing, so allow both 'tag' and 'tags' synonymously. Pick this also to 6.5, cause quite some examples in various repositories contain "\meta tags". Pick-to: 6.5 Change-Id: I2d0e59b4a0de27aa5f045b4d5f981c47aaf8b98c Reviewed-by: Qt CI Bot <qt_ci_bot@qt-project.org> Reviewed-by: Topi Reiniö <topi.reinio@qt.io>
* Doc: Document \sincelist QDoc commandTopi Reinio2023-03-072-0/+24
| | | | | | | Pick-to: 6.5 Change-Id: I925e1b1afbb62fb582a09921f244d4975f9dc881 Reviewed-by: <safiyyah.moosa@qt.io> Reviewed-by: Paul Wicking <paul.wicking@qt.io>
* QDoc: Drop support for renaming commands via qdocconf filesPaul Wicking2023-03-035-34/+6
| | | | | | | | | | | | | | | | | | | | For "compatibility reasons", support for renaming commands through an "alias" defined in a .qdocconf-file was introduced to QDoc. In particular, this was an aid when renaming QDoc's \input command to \include. This usage has since been unified in Qt, with the exception of in QDoc's own documentation project, and the more powerful \macro command can be exercised to achieve the same behavior. This feature's implementation obstructs efforts to make QDoc's code more thread safe. As there are no known usecases, remove support for renaming commands to pave the way for a more performant QDoc. [ChangeLog][QDoc] Support for the 'alias' variable in qdocconf-files is removed. Use QDoc's 'macro' construct instead. Fixes: QTBUG-111670 Change-Id: Ifcf8a47ee1e1940607cec4841e6ba06b493e6d24 Reviewed-by: Topi Reiniö <topi.reinio@qt.io>
* Doc: Update \brief description to be genericSafiyyah Moosa2023-02-282-16/+6
| | | | | | | | | | Update the description of \brief QDoc command to be generic and apply to any topic command. Update link targets. Fix spaces. Fixes: QTBUG-111391 Pick-to: 6.5 Change-Id: If41fd64ad420433aa022e7bb92506c06cfc0e76f Reviewed-by: Venugopal Shivashankar <Venugopal.Shivashankar@qt.io>
* QDoc manual: improve description of argument handlingPaul Wicking2023-02-201-5/+6
| | | | | | | | | | | Move the important block up, so that people notice in the first time they read the docs. Add a sentence to describe the point of enclosing arguments in curly braces. Fixes: QTBUG-109734 Pick-to: 6.5 Change-Id: I245ff686a43c6fd443afdf98a28cd9564e492ed7 Reviewed-by: Andreas Eliasson <andreas.eliasson@qt.io>
* qdoc: Drop remnants of unimplemented feature \generate examplefilesTopi Reinio2023-02-143-33/+1
| | | | | | | | | | | | | Previously QDoc provided a \generatelist example[files|images] <regexp> feature to list example files matching a specific regular expression, but it was left non-functional after changes to example documentation generation. Remove remnants of the related code paths and documentation. Pick-to: 6.5 Change-Id: Ibdaab6e6be3e4d87b60fa59966783827f0a264e1 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>
* Doc: Fix snippet indentation issues in QDoc manualTopi Reinio2023-02-072-1077/+1077
| | | | | | | | | Previous changes left inconsistent indentation in example code snippets. Pick-to: 6.5 Change-Id: I86e116455e22b513fbfdbacc65ac7e05b01b4c56 Reviewed-by: Andreas Eliasson <andreas.eliasson@qt.io>
* Doc: QDoc Manual: correctly output /*! and */ comment delimitersTopi Reinio2023-02-074-416/+405
| | | | | | | | | | | | | | | | | | | | | | | The QDoc manual has a lot of code snippets demonstrating the use of commands, and these comments include the C-style comment delimiters, /*! and */. However, because */ is forbidden to appear within a comment block (as it terminates it), the snippets included malformed versions of the delimiters. This made copy-pasting annoying as the snippets didn't represent valid QDoc syntax. Fix the issue by using a '*' argument passed to code quoting commands, allowing /\1! and \1/ to expand to the actual delimiters in the output. Also, * Replace the use of \code with \badcode for QDoc snippets, avoiding the needless parsing/highlighting of non-C++ code. * Fix other minor issues in passing. Pick-to: 6.5 Fixes: QTBUG-110142 Change-Id: Idcc4dc0fdfc6a8c7d368f3b2bc8f0dd8f1eb0843 Reviewed-by: Andreas Eliasson <andreas.eliasson@qt.io> Reviewed-by: Venugopal Shivashankar <Venugopal.Shivashankar@qt.io>
* qdoc: Remove demos-manifest.xml fileKai Köhne2023-01-271-4/+3
| | | | | | | | | | The separation between 'examples' and 'demos' is not used anymore. Also, Qt Creator since quite a long time does just read both files, and treat them exactly the same. Pick-to: 6.5 Change-Id: I307b32f1c87c849b0b8a1e19d7604fbbd5989d1f Reviewed-by: Topi Reiniö <topi.reinio@qt.io>
* qdoc: Ignore rest of the line for \inlineimageVenugopal Shivashankar2023-01-241-27/+21
| | | | | | | | | | | | | Inline images need not consider rest of the line as alt text, unless they are wrapped in a {}. Updated the qdoc manual to indicate that caption to an inline image must be wrapped in braces. Pick-to: 6.2 6.4 6.5 Done-with: Topi Reinio <topi.reinio@qt.io> Change-Id: I2098e8da2e9139bc6c022f36aa8432913546e863 Reviewed-by: Topi Reiniö <topi.reinio@qt.io>
* Revert "QDoc manual: Remove unnecessary braces"Paul Wicking2023-01-051-1/+1
| | | | | | | | | This reverts commit f8a7ade512252e48da3cd43388e5366688111efa. Reason for revert: Better fix is by improving the docs. Change-Id: I6b1acb21c2e392246cb9c81f42b702e592fa1f95 Reviewed-by: Topi Reiniö <topi.reinio@qt.io>
* QDoc manual: Remove unnecessary bracesPaul Wicking2023-01-051-1/+1
| | | | | | | | Fixes: QTBUG-109734 Pick-to: 6.5 Change-Id: Ibb6522cbab4d5f28198b63f170fe683fe6325314 Reviewed-by: Ahmad Samir <a.samirh78@gmail.com> Reviewed-by: Andreas Eliasson <andreas.eliasson@qt.io>
* QDoc: Remove unused overload of \meta commandPaul Wicking2022-12-301-7/+4
| | | | | | | | | | | | | | | 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: Fix documentation and configuration warnings about libclangUlf Hermann2022-12-161-2/+4
| | | | | | | | | | | | | The most important thing a user needs to know when installing libclang on linux is that they need the ClangConfig.cmake file. State that when we fail to find libclang. Also, add a note about LLVM_INSTALL_DIR to the documentation. Using LLVM_INSTALL_DIR is the cleaner option since the configure script should only look for LLVM-related packages in the LLVM installation. Change-Id: Iaa26a4e15955b60120f002a34ab8d7a00548a221 Reviewed-by: Paul Wicking <paul.wicking@qt.io>
* Doc: qdoc doesn't accept wildcard C++ defines anymoreKai Köhne2022-11-231-18/+3
| | | | | | | | | | Since the switch to clang, qdoc cannot process wildcard based defines anymore. Update documentation accordingly. Pick-to: 6.4 Change-Id: I3e1bf3234e17bcd46cbb4c2bd72ea33ad188fc9c Reviewed-by: Luca Di Sera <luca.disera@qt.io> Reviewed-by: Topi Reiniö <topi.reinio@qt.io>
* Doc: Fix typosAndreas Eliasson2022-11-111-2/+2
| | | | | | Pick-to: 6.4 6.3 6.2 Change-Id: Ie6caa2f8ec7f55db137010df775b6c44d4f0d2e5 Reviewed-by: Leena Miettinen <riitta-leena.miettinen@qt.io>
* Fix rowspans in qdoc manualThibaut Cuvelier2022-11-101-6/+6
| | | | | | | | No space is allowed in the value of rowspan and colspan. HTML parsers are laxer than DocBook ones in this regard. Change-Id: I2648497c4346f78dc40dcc276a18ee57286f56e7 Reviewed-by: Paul Wicking <paul.wicking@qt.io>
* QDoc manual: improve \qml descriptionPaul Wicking2022-10-141-1/+4
| | | | | | | | | I was wondering about why I should recommend \qml ... \endqml over \code ... \endcode, and this is what I understood from the explanation I got when I asked more knowledgeable people than I. Change-Id: I829992d2a63787d4c74397d3a40f3199a3e4169e Reviewed-by: Luca Di Sera <luca.disera@qt.io>
* Doc: QDoc Manual: Document the \wrapper commandTopi Reinio2022-09-292-0/+10
| | | | | | | | | | | This command is used in a number of OpenGL and Vulkan-related classes, and it's sole purpose is to suppress warnings that QDoc would otherwise generate for an undocumented, non-Qt API. Pick-to: 6.4 Fixes: QTBUG-106255 Change-Id: I7146ecd1a904cf170907cbb184dd8d06cca9bb12 Reviewed-by: Paul Wicking <paul.wicking@qt.io>
* qdoc: fix typo in variable name in documentationRolf Eike Beer2022-09-231-1/+1
| | | | | | Pick-to: 6.4 6.2 Change-Id: I9975638bff93e4d46e922ea0a864ea724cd4555a Reviewed-by: Kai Koehne <kai.koehne@qt.io>
* QDoc: Remove the "\newcode" and "\oldcode" command pairLuca Di Sera2022-09-132-16/+0
| | | | | | | | | | | | | | | The pair was deprecated in eb99338568dab0bd62144e1009974d5317b53037 and was marked as to be removed in Qt 6.4. As the release of 6.4 is near, we now remove all remaining code related to the two commands. [ChangeLog][qdoc] The deprecated \oldcode, \newcode commands were removed. Fixes: QTBUG-98500 Pick-to: 6.4 Change-Id: I06525d15836f07abca5ddfebe9eb557e9e9909a0 Reviewed-by: Kai Koehne <kai.koehne@qt.io>
* Doc: Remove usages of the second argument of a "\page" commandLuca Di Sera2022-09-081-2/+2
| | | | | | | | | | | | | | | | | | | | | | | | | | The "\page" command for QDoc, used to construct a standalone documentation page in the output documentation of a project, was able to take a second argument, apart from the first argument representing the name for the generated documentation page, that roughly represented the type of the page that was to be generated. This second argument was not actually used by QDoc, such that it had no meaningful effect. QDoc was recently modified to not support this second argument, internally, and officially removed its use. For technical legacy reason, QDoc will still support the usage of a second argument for a "\page" command, albeit it will do nothing, as before. To avoid confusion for future readers who might not be aware of the history of the "\page" argument and that will not find an explanation in QDoc's documentation anymore, the usages of the second argument in "\page" commands are now removed. Change-Id: I084eb315a17562c9f43e8c43a4af218968d62fbf Reviewed-by: Topi Reiniö <topi.reinio@qt.io>
* QDoc: Remove Node::PageTypeLuca Di Sera2022-09-081-26/+3
| | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | QDoc uses a series of internal structure, based on an inheritance tree with base `Node`, to represent elements that are documentable and their properties. For documentable elements that generate a documentation page in the output, such as a documented C++ class, a subtree of the hierarchy, starting at `PageNode`, is used. A `PageNode`, and more generally a `Node`, can have a "Page Type", representing the type of element that the output documentation should represent. This is implemented in terms of an enumeration and an internal memeber of that enumeration. Supposedly, originally there was almost no hierarchy of types for `PageNode`s, and the enumeration was used as a form of tagged union to discern the the type of page that the `PageNode` would produce to determine the valid operations on it and the required computations that should have been performed during a generation. At some point in QDoc lifetime, some of the types implied by `PageType` were promoted to actual types under a `PageNode` hierarchy, for example `ExampleNode`, such that the use of `PageType` was reduced. Today, `PageType` is used only when parsing a "\page" command, which generates a `PageNode`. The "\page" command, which declares that a comment-block should generate a standalone documentation page in the output that doesn't document any specific or code-level element, takes an argument representing the name of the generated file and, optionally, a second argument. The optional second argument is a bare string that, if of a specific form, is used to define the type of the generated `PageNode` that represents the page. For example, a second argument of form "api" would mark the `PageNode` with as being of type `PageType::ApiPage`. Generally, this information is not used at all during the rest of a QDoc execution, as none of the remaining `PageType` nodes that don't have an actual type require special handling. There is, albeit, one exception to this. When the second argument of a "\page" command is "attribution", the `PageNode` has type `PageType::AttributionPage`. This type is meaningful as it is later used to collect "Attribution Pages" for a certain module so that QDoc can generate a list of them in Qt's documentation. "Attribution pages" are a special type of page that are used in Qt's documentation to "attribute" usages of third-party libraries, so as to comply with their licensing. Those pages are only expected to be generated by "qattributionscanner", which takes care of parsing json-defined attribution metadata for third-party libraries to generate the required attribution page. Thus, while `PageType` is generally not required, this specific behavior has to be supported. Hence, we remove `PageType`, replacing it with an equivalent behavior that only handles attributions. The `PageType` enum in `Node` is now removed. `Node::pageType`, the getter for the current `PageType` of `PageNode`, the two `Node::setPageType` overloads, the setter for the `PageType` of a `PageNode` and `Node::getPageType`, a converter from `Node::NodeType` to `Node::PageType`, were removed as they have no meaning anymore. The member `m_pageType` of `Node`, that contained the current "Page Type" of a `Node` instance, was removed as it lost its use. The constructor for `Node` is now modified to not set a `PageType`. The constructor for `PageNode` that took a `PageType` to set was removed, as it lost its use. As a consequence, the code that handles the "\page" command in `CppCodeParser::processTopicCommand`, was removed call the constructor for `PageNode` that does not require a `PageType`. Furthermore, the same code was modified to not process the second argument of a "\page" command anymore. The parsing and retrieval of the second argument is tied to the current model used by `DocParser`, which is general for topic commands, and cannot be easily removed, such that it will still be valid to pass a second argument albeit it will be completely ignored. The documentation in QDoc's manual that explains the usage of "\page"'s second argument was removed as a consequence. The code in `QDocIndexFiles` that writes and reads a `PageNode` was modified to ignore the type, where possible, while keeping a similar structure for the produced format. To preserve the "Attribution Pages" behavior, a new member, `is_attribution`, was introduced in `PageNode`, acting as a flag, defaulting to false, that is set when a `PageNode` is an "Attribution Page". A setter that turns on the flag, `markAttribution`, and a getter that reads the flag, `isAttribution`, were added to `PageNode`. Albeit in a more contained scope than the previous `Node` scope, the new members are too broadly scoped compared to their actual usages. For example, a `ClassNode` is allowed to be an "Attribution Page" albeit we don't expect that to make sense. Due to the low granularity of QDoc's internal representation, fixing this would either require a bigger refactoring or the introduction of new idioms, both of which are not an amount of work that is intended to be undertaken as of this patch. The code in `Aggregate::findAllAttribution`, that is used to build the list of "Attribution Pages" in a module, was modified to use the new methods to discern whether a child node is an "Attribution Page". A new command, "\attribution", was added to allow a user to mark a "\page" as an attribution. The command is not intended to take any arguments and will simply mark the documented page as being an "Attribution Page". No user-facing documentation for the command is provided as the command is intended only to support the internal "qattributionscanner" behavior in Qt's documentation and should not be used manually or in other places at the current time. The necessary code to handle the command was added to `CppCodeParser`, turning on the relevant flag when the command is found and producing a warning if the command is not in a "\page" comment-block. Due to the limited granularity of QDoc's datatypes, the command will incorrectly pass for non "\page", non `Aggregate` comment-block, such as "\example", where it could produce seemingly incorrect documentation. This is something that should be addressed separately in a general look at QDoc's internal structures. The code in `QDocIndexFiles::readIndexSection` that reads back a `PageNode` was modified to call `PageNode::markAttribution` when reading back a `PageNode` that is an attribution. The generator of QDoc's "Attribution Pages" for "qattributionscanner" was modified to output an "\attribution" command on the line following the "\page" command produced for an "Attribution Page" instead of generating an "attribution" argument for the "\page" command itself, to be compliant with the new interface. Change-Id: I41405fd4db884d98463a43bff8815c4504dc00ea Reviewed-by: Topi Reiniö <topi.reinio@qt.io>
* QDoc: Remove unfinished support for documenting javascriptLuca Di Sera2022-09-075-26/+16
| | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | 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>
* QDoc manual: drop extra backslash in macroPaul Wicking2022-08-291-1/+1
| | | | | | | | | I'm pretty sure this was intended to use the macros, not show the macros in rendered text. Pick-to: 6.4 6.3 6.2 Change-Id: I3ea75df206e6b43cb7fec606dabdf9bd3b9564db Reviewed-by: Luca Di Sera <luca.disera@qt.io>
* QDoc manual: improve Clang for QDoc sectionPaul Wicking2022-08-291-9/+14
| | | | | | | | Reflow long lines as part of edit. Pick-to: 6.4 6.3 6.2 Change-Id: I73652a5a769918845f16d24a3d8673038f63bb85 Reviewed-by: Luca Di Sera <luca.disera@qt.io>
* Doc: Don't mention qdoc's cpp.ignoredirectives, cpp.ignoretokens anymoreKai Köhne2022-08-222-116/+2
| | | | | | | | | | The settings are noops since the switch to clang backend. Pick-to: 6.4 Task-number: QTBUG-104903 Change-Id: I09b62c242e8d6fd8613916e33df786da313e6634 Reviewed-by: Paul Wicking <paul.wicking@qt.io> Reviewed-by: Sona Kurazyan <sona.kurazyan@qt.io>
* QDoc: Add support for en-dash and em-dashPaul Wicking2022-08-181-0/+97
| | | | | | | | | | | | | | | | | | | | | | | | | | | | 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 manual: Minor correctionsPaul Wicking2022-08-181-6/+6
| | | | | | | | | | | | | Fix the \sa link for the \uicontrol description, as it ends up at the bottom of the page and not in the expected context. Change the target for the \\ sequence as it's a sequence, not a command. Fix its broken description, and make a couple minor touchups elsewhere. Change-Id: I6f37226cc696d8ac5e83fa4a153eaf263d7e4b4d Reviewed-by: Topi Reiniö <topi.reinio@qt.io>
* Use similar formatting for raw qdoc outputThibaut Cuvelier2022-08-101-10/+10
| | | | | | | This is mostly the only raw qdoc HTML output (with the exception of tables) that is not wrapped in quotations. Change-Id: Iecdd97062ccc2e00b3c434203409cf15611fdb9b Reviewed-by: Paul Wicking <paul.wicking@qt.io>
* QDoc manual: Fix typoPaul Wicking2022-08-071-1/+1
| | | | | | | | The escaped backslash ends up in the output as it's wrapped by the \c{}. Change-Id: Ie13f8155f6de1d263c97aab6e4866cbf4d9ab04c Reviewed-by: Luca Di Sera <luca.disera@qt.io>
* Doc: QDoc Manual: Document the examplesinstallpath qdocconf variableTopi Reinio2022-07-252-9/+61
| | | | | | | | | | | | | This variable was briefly mentioned in the breakdown of a sample .qdocconf file but not properly documented. Add a section for it in the list of variables. Clean up the sample .qdocconf file in passing. Pick-to: 6.4 Fixes: QTBUG-104633 Change-Id: Icf8ee395f1add63e6382e1f0c715b22f4f3bc7c6 Reviewed-by: Paul Wicking <paul.wicking@qt.io>
* qdoc: Introduce \modulestate commandTopi Reinio2022-07-151-0/+27
| | | | | | | | | | | | | | | | | | | | | | | | 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>
* qdoc: Make types inherit \since statement from their module docsTopi Reinio2022-07-131-0/+6
| | | | | | | | | | | | | | | 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>
* Doc: Make small changes to the \group command descriptionAndreas Eliasson2022-07-041-2/+2
| | | | | | | | | | | With the current description of the group html file name, <lower-case>\e{group}.html, I get the impression that the word 'group' is suffixed to whatever comes before it. Which is not the case. Change-Id: I1a609efc46213f98a1cb6856be4015e251a0eba0 Reviewed-by: Luca Di Sera <luca.disera@qt.io> Reviewed-by: Topi Reiniö <topi.reinio@qt.io>
* Fix typo in \ingroup documentationKai Köhne2022-06-271-1/+1
| | | | | | Pick-to: 6.2 6.3 6.4 Change-Id: I286c678aa4c9f87832c875eb10fd5a9416181130 Reviewed-by: Leena Miettinen <riitta-leena.miettinen@qt.io>
* Doc: QDoc Manual: Fix documentation for \qtcmakepackage commandTopi Reinio2022-06-141-12/+15
| | | | | | | | | | | | | The \raw HTML used in the example output did not close the <table> and <div> elements, causing the page to be misformatted. Add the closing elements and wrap the example output in <blockquote>. Fix the related \code snippet to have proper QDoc comment delimiters. Pick-to: 6.4 Fixes: QTBUG-103863 Change-Id: I13bd78f5d00e2dfe31d0f1c79f1fe0af543d76bb Reviewed-by: Nicholas Bennett <nicholas.bennett@qt.io>
* qdoc: Use QML-specific code marker when parsing a QML topicTopi Reinio2022-06-102-30/+47
| | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | The \code command is used widely to document also QML code snippets, however, QDoc failed to detect the code as QML because the default code marker is the CppCodeMarker. The consequence was that QDoc failed to detect and auto-link to QML types in code snippets. The default marker to use depends on the 'language' configuration variable and pure QML documentation projects can set it to QML instead. Many projects consist of both C++ and QML module docs however, and using a single project-wide setting is less than optimal. As a compromise, use the QML marker for \code snippets appearing within QML-specific topics as the default code marker. Ensure that the code is detected as QML - this prevents unexpected warnings for parsing failures typically seen with the \qml command. Note that the downside of the chosen solution is that QML topic command must appear before the \code commands for the automatic marker selection to take place. This can't be helped as all commands are parsed sequentially and we don't know the topic beforehand. Typically this is not a problem as the convention is to start the documentation comment with a topic command, even though QDoc doesn't strictly require it. Task-number: QTBUG-103791 Change-Id: I87f2549c7c258a15fc02f64f65ef7fa0b28b5a68 Reviewed-by: Topi Reiniö <topi.reinio@qt.io>
* Remove references to DITA and replace them by DocBookThibaut Cuvelier2022-06-032-7/+7
| | | | | | | DITA support was removed years ago (e.g., see QTBUG-83930) Change-Id: Ie1b8fc840998e9c6b468f1962ddab959357745c4 Reviewed-by: Luca Di Sera <luca.disera@qt.io>
* doc: Add some bits about using the \fn command for hidden friendsLuca Di Sera2022-05-231-0/+19
| | | | | | | | | | | | | | | | | | | The Qt project uses hidden friends quite often as a result of the changes started in QTBUG-87973. QDoc is able to document hidden friends but requires the relevant comment-block to refer to the friend as a member of the enclosing class. This syntax doesn't mimic what could be an intuitive way, from a C++ point of view, to refer to the friend and has proved to be confusing in the past (QTBUG-101649). As we don't currently plan on relaxing this requirement, some bits of documentation was added to the QDoc manual, under the `\fn` command section, to warn about documenting hidden friends. Change-Id: Iabb7f991804cb5c5cae98284c79b98104d04e8b4 Reviewed-by: Topi Reiniö <topi.reinio@qt.io>
* Use SPDX license identifiersLucie Gérard2022-05-1919-496/+38
| | | | | | | | | | | 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>
* Doc: Update documentation of \since command in the QDoc manualTopi Reinio2022-05-161-8/+19
| | | | | | | | | | | | Remove obsolete statement about \since command's relation to the 'project' configuration variable, and document the currect behavior. Link to \value command as it allows an optional since clause specific to individual enum values. Pick-to: 6.3 6.2 Change-Id: I11034474a103db0155a91359c9a10956e8d2a4e0 Reviewed-by: Leena Miettinen <riitta-leena.miettinen@qt.io>
View Lorry Controller Status