summaryrefslogtreecommitdiff
path: root/src/qdoc/node.cpp
Commit message (Collapse)AuthorAgeFilesLines
* clang-format QDocPaul Wicking2019-12-171-249/+214
| | | | | | | | | | | | | | | | This patch is the result of formatting all of QDoc's source with clang-format. The clang-format style is from the qt5 super repo's _clang-format definition. The purpose is unify the style across the code, to avoid spending too much time on style related issues in reviews and cleanup patches. Future changes to QDoc can benefit from using git-clang-format in combination with the git commit hook provided in qtrepotools.git as mentioned in this email to the dev list: https://lists.qt-project.org/pipermail/development/2019-October/037682.html Change-Id: I8af6a051c8334b5f35862a4dcd3becce8ac500c2 Reviewed-by: Martin Smith <martin.smith@qt.io>
* QDoc: Use QVector instead of QListPaul Wicking2019-12-121-6/+6
| | | | | | | | | | | Replace the use of QVector in most of QDoc. Also, remove one redundant C-style cast to int for result from method call that returns an int. As this happened in a macro, the result is removing a whole bunch of nagging from code inspection. Fixes: QTBUG-80669 Change-Id: Ib1aed95e01eaddd1e1213a145e815a0c4753ac67 Reviewed-by: Mårten Nordheim <marten.nordheim@qt.io>
* QDoc: Minor adjustment/cleanupPaul Wicking2019-12-111-1/+1
| | | | | | | Pre-increment instead of post-increment for efficiency and readability. Change-Id: I10b33360dd36cd1d0f4338441c1ad4724551e80e Reviewed-by: Topi Reiniö <topi.reinio@qt.io>
* QDoc: Get rid of unnecessary castsPaul Wicking2019-12-111-1/+1
| | | | | | | Drop casting ints to int. Change-Id: I571f3e245bfc97a7c0c7bea5bedbf0ed5ab04c60 Reviewed-by: Topi Reiniö <topi.reinio@qt.io>
* QDoc: Clean up loops with iteratorsPaul Wicking2019-12-101-96/+67
| | | | | | | | | | | - Use ranged-based fors where applicable. - Use auto keyword for iterators. - Move a few variable declarations to where they're to be used. - Update docs where applicable. Fixes: QTBUG-80536 Change-Id: I859440b96428dec4ef108b01d391479d3f8dbd83 Reviewed-by: Topi Reiniö <topi.reinio@qt.io>
* QDoc: remove dead/unreachable code reported via coverityLevon Sargsyan2019-12-061-1/+0
| | | | | | | | | | | | | This patch removes structuraly and logically dead code, reported via coverity scan and reported to appropriate categories of "dead code". Coverity-Id: 11018 Coverity-Id: 226101 Coverity-Id: 226127 Change-Id: I1930299c57ff10875c5b7e2df51895d9dee42fac Reviewed-by: Paul Wicking <paul.wicking@qt.io> Reviewed-by: Levon Sargsyan <levon.sargsyan@qt.io>
* qdoc: Restore alphabetical ordering of generated type listsTopi Reinio2019-12-031-45/+13
| | | | | | | | | | | | | | | | | | | | The comparison function used for sorting compares fullTitle() strings for PageNode items. When the class hierarchy was refactored, this had the unintended effect where this comparison was applied to lists of C++ and QML types as well - the full title is empty for these, so we ended up comparing the physical location of the type declarations instead. Fix this by preferring the fullName() over fullTitle() when comparing, as the former is what the visible list item names are generated from. Make the comparison function easier to read and maintain by introducing a preprocessor macro. Fixes: QTBUG-80259 Change-Id: I3f35aa80f1a90a6817f836146976d73b857df820 Reviewed-by: Martin Smith <martin.smith@qt.io> Reviewed-by: Paul Wicking <paul.wicking@qt.io>
* qdoc: Fix issues with shared comment nodesTopi Reinio2019-10-161-19/+9
| | | | | | | | | | | | | | | | | | | | | | | | | | | | | | QDoc stores <sharedcomment> elements to the .index correctly, but the nodes that were sharing a comment were added after the shared comment. This meant that a shared comment node (SCN) could not find any of its members as they hadn't been read in yet. Fix this by delaying the creation of a new SCN until we have a list of sharing nodes. Also fix other related issues: - Generate content also for non-function SCN members. - Make SCN adopt the genus of a member when adding one. - Fix Node::isPropertyGroup() to return true for actual property groups (not all QML properties that share a comment) and fix usage of that method. - Fix linking to property groups when searching by the group name. - Restore indentation of property group members both in the summary section and in the All Members file. Fixes: QTBUG-79204 Change-Id: I1702f39b178f52444436b800d4fe9cb99f976a60 Reviewed-by: Paul Wicking <paul.wicking@qt.io> Reviewed-by: Martin Smith <martin.smith@qt.io>
* QDoc: minor cleanup in Generator and NodePaul Wicking2019-10-031-3/+3
| | | | | | | | | | | | | | | | Generator: * Don't sort container of QMap's keys as they're already sorted. The container can thus be made const. Node: * Make getter const * Remove qAsConst used in a ranged for loop in a const method. Both: * Remove qAsConst rendered superfluous. Change-Id: I8f65f87c0ed372573cdd17f96e95cd2732effdd7 Reviewed-by: Mårten Nordheim <marten.nordheim@qt.io>
* QDoc: Use range-based for instead of foreachPaul Wicking2019-09-281-94/+92
| | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | This change replaces the use of foreach with range-based for throughout QDoc. It also ensures that the loop body doesn't modify the container being iterated over, by: - Making a const copy when the container is a member variable or the result of an expression, and iterating over that copy. This is the preferred approach. - Using qAsConst() when the container is a (static) member variable or local to the method and not const. The latter is typical where the collection is sorted immediately before the loop. In two cases (doc.cpp), replaced Q_FOREACH + delete with qDeleteAll. In two cases (cppcodeparser.cpp), the range declaration is replaced within the loop statement. These rewrites express the behavior clearer than the original code. In two cases (codeparser.cpp), use a range-based for instead of a while loop where the condition is an iterator, for more expressive code. Finally, use the auto keyword where appropriate and improve a few variable names. QDoc warning count and generated output is unchanged after this refactoring. Change-Id: I64f02d24dca373a3a41402d535382e2c526bb55e Reviewed-by: Mårten Nordheim <marten.nordheim@qt.io>
* Merge remote-tracking branch 'origin/5.13' into 5.14Qt Forward Merge Bot2019-09-271-4/+4
|\ | | | | | | Change-Id: I5c06b3e0177fcccd988620ab269f75632689a54c
| * qdoc: Fix issues with related non-membersTopi Reinio2019-09-201-4/+4
| | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | The \relates command sets a node as a related non-member of another node, and sets that node as the new parent. However, the old parent still holds a pointer to the newly-adopted node; this is needed for searching. Some locations in the code did not handle the possibility of parent's children reporting a different node as their parent. Skipping these nodes when traversing the node tree eliminates duplicate entries from .qhp files. These duplicates are however needed in the .index files for linking to work, as links may reference both the global namespace and the scope the node relates to. Remove these duplicates from .qhp files, and omit parent names when generating 'id' attributes for related non-members. This reverts the .qhp content to what it was in Qt 5.12. Parents of related members must be skipped when resolving the full name of the node, otherwise searching for the name is likely to fail. Non-members related to a header file did not receive a valid location ('href'). Task-number: QTBUG-78474 Change-Id: Ie126219e8101beaa051f2f4a1a9f93c731fc8168 Reviewed-by: Paul Wicking <paul.wicking@qt.io> Reviewed-by: Martin Smith <martin.smith@qt.io>
* | QDoc: Remove empty destructors and add missing override keywordPaul Wicking2019-08-121-8/+0
| | | | | | | | | | | | | | | | | | | | | | This change removes reduntant destructors. It also adds the 'override' keyword to overridden destructors to remove warnings from clang-tidy in Creator. The patch also replaces two instances of 0 as nullptr constant. Change-Id: I576c248b7d4637249d167d7bfb8885af4f7811ff Reviewed-by: Edward Welbourne <edward.welbourne@qt.io>
* | QDoc: Clean up whitespacePaul Wicking2019-08-081-205/+205
| | | | | | | | | | | | | | | | | | | | | | Ensure that QDoc conforms to Qt style, whitespace edition. For the most part, the change involves moving the pointer operators. Also remove whitespace following an opening parenthesis, or immediately preceding a closing one. In some cases, adjust the following line accordingly in methods that span multiple lines. Change-Id: I56ae125a2acf09c669c0a73dc814d05f13575f39 Reviewed-by: Martin Smith <martin.smith@qt.io>
* | Doc: Fix typos and formatting in QDoc documentationPaul Wicking2019-08-081-58/+81
| | | | | | | | | | Change-Id: Iad9709f9bbbfad98b7db0c14eb9a425c15c0ef9a Reviewed-by: Martin Smith <martin.smith@qt.io>
* | qdoc: Document qdoc's Node classesMartin Smith2019-08-071-694/+1924
| | | | | | | | | | | | | | This update is adding qdoc comments to document qdoc's Node hierarchy. Change-Id: I756141f882a8dfbeb0076915a7b77f47e06a04b5 Reviewed-by: Paul Wicking <paul.wicking@qt.io>
* | QDoc: Ensure all includes are uniform and according to stylePaul Wicking2019-08-031-6/+8
| | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | Housekeeping. Includes are organized after recommended best practice and organized in the following order: - include self (i.e. include own header) - include local files - include Qt, e.g. <QtCore/qstring.h> - include Qt private - include externals, e.g. stdio.h in alphabetic order within each block, aside from accommodating #if-ery, in which includes follow the block they belong to. Also, updated copyright notice to year of latest edit in each file. Change-Id: I1e6b215f172fd5373d57016f7678b88b9e73231e Reviewed-by: Edward Welbourne <edward.welbourne@qt.io>
* | Merge remote-tracking branch 'origin/5.13' into devQt Forward Merge Bot2019-08-021-15/+41
|\ \ | |/ | | | | Change-Id: Id63def71d27afe593d991478ebc44b7052194e47
| * qdoc: Fix "Inherited By" outputMartin Smith2019-07-311-15/+41
| | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | The "Inherited By" list was incomplete for QObject (and other classes) because classes that inherited QObject from modules outside QtBase were not being included. This update cleans up the maintenance of a class's base class and derived class information so that the "Inherited By" list is more correct. Note that the "Inherited By" list can't be guaranteed to be complete because, for example, classes in external modules might inherit QObject, but if those external modules are not listed as dependencies of QtCore, QObject won't know about those classes. Task-number: QTBUG-77126 Change-Id: Ia0be361f9e909fee04e9680d4219c96812306712 Reviewed-by: Paul Wicking <paul.wicking@qt.io>
* | Merge remote-tracking branch 'origin/5.13' into devQt Forward Merge Bot2019-07-301-5/+7
|\ \ | |/ | | | | Change-Id: I008f970a8260f059f7d4d615a12a184fa5877366
| * Doc: Replace "return 0" with "return \nullptr" in QDoc's node.cppPaul Wicking2019-07-231-5/+7
| | | | | | | | | | Change-Id: Idfaf778aa13cb461bb9e0db344033aa8147a51d3 Reviewed-by: Martin Smith <martin.smith@qt.io>
* | Merge remote-tracking branch 'origin/5.13' into devQt Forward Merge Bot2019-07-231-3/+74
|\ \ | |/ | | | | Change-Id: I6583a8d818ef437d24384c63683da7669cd62d87
| * qdoc: Fix the \reimp command outputMartin Smith2019-07-221-2/+73
| | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | When qdoc finds \reimp in a function node comment, it searches the parent class node's base classes to find the function node for the function that is overridden. When it finds this node it prints the "Reimpliments: Yyy::Xxx()" line in the current function node's documentation. This was not working correctly when the reimplemented function was in a different module. The problem was that the fact that the function in the base class had been documented was not recorded in the index file. This update fixes that problem. Now every element that was documented is given the "documented" attribute in the index file set to true. Sometimes, \reimp is used to say that a function reimplements an access function for a property in a base class. This update handles that case as well. See QToolButton::sizeHint(), for example. This change introduces a 6 new qdoc errors in QtBase about \reimp functions for which a documented base class function was not found. Change-Id: Idd444958c3118ade97642bf84781166e6ca8f036 Reviewed-by: Paul Wicking <paul.wicking@qt.io>
| * qdoc: Add hasDoc() test to findOverriddenFunction()Martin Smith2019-07-171-1/+1
| | | | | | | | | | | | | | | | | | | | | | | | | | | | | | When qdoc finds \reimp in a function node comment, it searches the parent class node's base classes to find the function node for the function that is overridden. When it finds this node it prints the "Reimpliments: xxx()" line in the current function node's documentation. But the search for the overridden function is meant to be recursive. It was working recursively, but the search was ending prematurely on a function node that had no documentation. In that case, the search should go higher in the inheritance tree to find an overridden function that is documented. This update adds the hasDoc() test to that search function to ensure that the final matching function does have documentation. Change-Id: Iaf6481f8b3aa98df0d0ef188912f1338316f079a Reviewed-by: Paul Wicking <paul.wicking@qt.io>
| * qdoc: Add hasDoc() test to docMustBeGenerated()Martin Smith2019-07-161-1/+1
| | | | | | | | | | | | | | | | | | Even if a class declaration appears in an _p.h file, a doc page must be generated for it if hasDoc() returns true for the class node. Task-number: QTBUG-77026 Change-Id: I6ca7d614383aadfb6ffcae1c8e021d2998de6a9d Reviewed-by: Paul Wicking <paul.wicking@qt.io>
* | Merge remote-tracking branch 'origin/5.13' into devQt Forward Merge Bot2019-07-111-7/+27
|\ \ | |/ | | | | | | | | | | Conflicts: .qmake.conf Change-Id: If0d8f3f1dc3be742bb2fadb7873eabdd6f46d3d1
| * qdoc: Revise ClassNode::docMustBeGenerated()Topi Reinio2019-07-041-7/+3
| | | | | | | | | | | | | | | | | | | | | | | | | | | | Earlier implementation was incorrect as it omitted generating output for classes that have only non-function members. Also, it incorrectly generated output for private, non-documented classes. Simplify the criteria for generating output; filtering based on the appearance of 'Private' string is not necessary for Qt, and may cause problems for projects external to Qt. Fixes: QTBUG-76892 Change-Id: Ieee6a693f887cbc0244753298f13a9b411801d56 Reviewed-by: Martin Smith <martin.smith@qt.io>
| * qdoc: Ensure that doc for header file nodes is writtenMartin Smith2019-07-041-3/+20
| | | | | | | | | | | | | | | | | | | | This update fixes a regression caused by the introduction of the docMustBeGenerated() function. The doc for header file nodes was not being generated because docMustBeGenerated() returned false for the header file nodes. Change-Id: I8bafd9e2ae96f41c8e7592403e3d9722797e5c24 Reviewed-by: Topi Reiniö <topi.reinio@qt.io>
| * qdoc: Fix \headerfile generationTopi Reinio2019-05-141-0/+7
| | | | | | | | | | | | | | | | | | | | | | | | Commit 72eac2f5 introduced a regression where \headerfile pages never generated any output. Since that commit, Node::docMustBeGenerated() is called for HeaderNodes, and we need to override it; otherwise the default base implementation gets called, and it simply returns false. Fixes: QTBUG-75790 Change-Id: I4932d5ba8dd595ad4d18033f77e62b14b54f8263 Reviewed-by: Martin Smith <martin.smith@qt.io> Reviewed-by: Paul Wicking <paul.wicking@qt.io>
* | Fix deprecation warnings about deprecated container conversionsFriedemann Kleint2019-05-231-4/+6
|/ | | | | | | | | Fix warnings introduced by qtbase/92f984273262531f909ede17a324f546fe502b5c. Change-Id: Iaca85ad36591f7208f63305b885e7ff59c014a72 Reviewed-by: Christian Ehrlicher <ch.ehrlicher@gmx.de> Reviewed-by: Lars Knoll <lars.knoll@qt.io>
* qdoc: Make QDoc warn about undocumented public classesMartin Smith2019-05-061-9/+31
| | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | QDoc was marking all undocumented public API elements as "internal" and "private" because most of these undocumented elements should not be documented. The standard way to tell QDoc not to warn about an undocumented elemewnt in the public API is to give it a QDoc comment with the command "\internl" in it. But it was decided this would require too much work to eliminate all the warnings, because there are so many undocumented elements in the Qt public API that we really don't want to be documented. So we decided to just mark them all as both internal and private in QDoc itself, and that eliminated a great many useless QDoc warnings. But it also meant that QDoc would no longer warn when a public element was left undocumented by mistake. This is most often seen in C++ classes that are in the public API but are not documented. QFutureInterface is an example of a class that is not documented but should be documented because it is useful. This change lets QDoc warn that a class in the public API was not documented with a \class comment. Special cases: 1. If the undocumented class has no members, don't warn that it was not documented with a \class comment. 2. If the undocumented class's name contains the word "Private" it is probably not meant to be in the public API, so don't warn that it has no \class comment. 3. If the undocumented class has no function members, then don't warn that it has no \class comment. 4. If the undocumented class is marked DontDocument, then don't warn that it has no \class comment. The other part of this change relates to item 4 above. To mark a class or struct as DontDocument required adding a new topic command to QDoc. The new topic command is \dontdocument. The argument to this command is a list of class and struct names. The list is enclosed in parentheses. For example: \dontdocument (QMacAutoReleasePool QIncompatibleFlag ... QTextCodec::ConverterState QThreadStorageData) QDoc looks up each name in the list and marks it DontDocument. The documentation generator then sees the node is marked DontDocument and ignores the node. This makes it a lot easier to tell QDoc which public classes and structs should not generate the warning about no documentation. Task-number: QTBUG-57183 Change-Id: I7eee48de03ca7aeb72c63ae90ba373503d41612d Reviewed-by: Topi Reiniö <topi.reinio@qt.io>
* qdoc: Fix \headerfile requisite table and title generationTopi Reinio2019-05-061-0/+9
| | | | | | | | | | | | | | | Using \headerfile did not call addIncludeFile() on the Aggregate, so the requisite table in the generated HTML contained an empty '#include <>' statement. Also, remove the 'Header' prefix from the generated title, as it produced titles that look odd, e.g. 'Header Global Qt Declarations'. Replace the title with a full title that contains the name of the header file, e.g. '<QtGlobal> - Global Qt Declarations'. Task-number: QTBUG-75570 Change-Id: Iccc248dcbcbfee85ca15e802e671ffcf9b9c10fe Reviewed-by: Martin Smith <martin.smith@qt.io>
* qdoc: Don't report override error when reimp is usedMartin Smith2019-04-051-5/+6
| | | | | | | | | | qdoc was reporting an error when the reimplementation of a virtual function that was documented in the base class was given a qdoc comment in the derived class that only contained the \reimp command. When the reimp command is used, the error should not be reported. This change implements that. Change-Id: I6905e35b4e9c3df12617446c04eb9ea6d1804832 Reviewed-by: Paul Wicking <paul.wicking@qt.io>
* qdoc: Search for QML type before creating itMartin Smith2019-04-021-10/+10
| | | | | | | | | | | | | | | | | | | | Because we have QML types that represent C++ classes, it is possible for qdoc to process a \qmlproperty command before it has processed the \qmltype for the QML type where the QML property belongs. This is because the \qmlproperty command can appear in a different .cpp file from the one containing the \qmltype command. If the .cpp file is parsed first, the QML type node won't exist when the \qmlproperty is processed, resulting in a qdoc error. This update forces qdoc to always check for the exist of the QML type before creating it and before creating any QML properties for it, and if the QML type does not exist, create it. If it does exist, use it. Change-Id: I78705aa95ee5bf3abc2e17fb2b6cd52191d54b68 Reviewed-by: Qt CI Bot <qt_ci_bot@qt-project.org> Reviewed-by: Paul Wicking <paul.wicking@qt.io>
* qdoc: Eliminate need for the property group commandsMartin Smith2019-04-021-145/+10
| | | | | | | | | | | | | | | We have been using the \qmlpropertygroup command to document complex properties. we also have the \jspropertygroup but it hasn't been used. However, we also have the shared comment concept, which we have used for documenting groups of functions. This update changes qdoc to use the shared comment concept for QML and JS property groups. The property groups commands are therefore no longer needed. But there are several uses of the \qmlpropertygroup command, and qdoc still recognizes these, although it uses the shared comment concept to handle them. The property group commands will be removed from the qdoc manual in a later update. Change-Id: Ie98638546756fd1a70067a7cd483c3b962c02954 Reviewed-by: Paul Wicking <paul.wicking@qt.io>
* qdoc: Use C++ 11 typed enums for the node enumerationsFriedemann Kleint2019-03-151-23/+23
| | | | | | | | | This allows for removing many ugly C-style casts. Change-Id: I3ea55a421989122d56ddc387a861e38fb459caff Reviewed-by: Martin Smith <martin.smith@qt.io> Reviewed-by: Qt CI Bot <qt_ci_bot@qt-project.org> Reviewed-by: Paul Wicking <paul.wicking@qt.io>
* qdoc: Fix duplication of nodes in index filesTopi Reinio2019-02-271-3/+6
| | | | | | | | | | | | | Aggregate class maintains a QMap of child nodes that is used for searching. PageNode entries may be added in the map multiple times, both with name() and title() as the key. When returning a list of non-function children, duplicates are now removed. Task-number: QTBUG-74009 Change-Id: I7e5df359313a53fa3b5bc4f9efa6e3ac6ea11eab Reviewed-by: Martin Smith <martin.smith@qt.io>
* qdoc: Improve function overload handlingTopi Reinio2019-02-131-7/+32
| | | | | | | | | | | | | | | When QDoc calls Aggregate::normalizeOverloads(), process \internal function nodes last. This ensures that they get assigned overload numbers higher than the public ones, and adding internal overloads no longer shuffle around the public HTML anchors (that are based on the overload numbers). Also, when searching for functions, ensure that we don't return an \internal overload if a matching public one exists. This gets rid of a number of linking warnings. Change-Id: Idaac077e2f88d310e3261bf5b4c3df33ca02f873 Reviewed-by: Martin Smith <martin.smith@qt.io>
* QDoc: Code cleanup, use nullptr for nullptr constantsPaul Wicking2019-02-081-17/+17
| | | | | | | | | | Replace 0 as nullptr constant with nullptr. Remove reduntant semi-colons after member function definitions. Adjust whitespace on lines otherwise touched. Change-Id: I6af218ca8377611040360e0a3da392e7cffd29e9 Reviewed-by: Martin Smith <martin.smith@qt.io> Reviewed-by: Qt CI Bot <qt_ci_bot@qt-project.org>
* qdoc: Correct ref pages for inner classesMartin Smith2019-02-081-19/+62
| | | | | | | | | | | | | | | | | | | | | | This update corrects the documentation pages for classes, structs, and unions that are declared inside a class or a struct. In Qt, a struct is often declared inside a class. For such internal declarations, the requirements for making the inner entity available were incorrectly shown. All that is really necessary is to include the parent class. So the requirements for including the inner entity are now replaced with, for example, "Struct State is declared in class QAccessible," where QAccessible becomes a link to the reference page for that class. It was easier to implement this change by teaching qdoc to recognize structs and unions in addition to classes, so that is also included in this change. Change-Id: I1a0d46ef19a130506c7bcbf77b46e298f6ab2f71 Task-number: QTBUG-66872 Reviewed-by: Qt CI Bot <qt_ci_bot@qt-project.org> Reviewed-by: Paul Wicking <paul.wicking@qt.io>
* qdoc: Major clean-up of FunctionNode and parameter processingv5.13.0-alpha1Martin Smith2019-02-061-653/+995
| | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | This update was motivated by the need to correct two known issues in qdoc. First, linking to overloaded functions failed in some cases because the overloads were not numbered consistently, causing links to go to the wrong overload or to nowhere at all. Second, the mechanism for handling the \relates command didn't support using it to relate a function to more than one class. For example, there are many global qHash() functions spread around QtBase. Each is meant to compute a hash index for an object of some class type, so the object can be inserted into a QHash map for that class type. It is then desired to relate qHash(type Xxx, int seed) to both QHash<type> and class Xxx, so that the documentation for that qHash() function appears as a related non-member function of both QHash<type> and class Xxx. The example above also illustrates the overload numbering problem, because all these qHash() functions are overloads of the name qHash. To make matters worse, they are not all in the same module. Most of them are in QtCore, but a few are in QtNetwork, and this distribution problem will become worse over time as more qHash() functions are added. Prior to this update, qdoc was unable to relate a function to something in a different module, or it didn't always work. While designing a fix for these issues, it became clear that the processing of the FunctionNode and the function parameters would have to be rewritten. That's what this update does. These are the main points: 1. A new subclass of Node is added to act as a proxy for a class in another module. This ProxyNode acts as a place holder for the functions (and possibly other elements) that are related to a class in another module. This is used for the qHash() functions in QtNetwork that are related to QHash in QtCore. qdoc generates an html file named qtnetwork/qhash-proxy.html that contains the documentation for these functions. But these functions are listed as related non-members on the QHash class reference page in the qtcore output directory. They are listed there in the summary, but they link to the qhash-proxy.html page in qtnetwork. 2. A new, Parameters class is added to qdoc (parameters.h and parameters.cpp), and the class Parameter is moved there from node.h. class Parameters replaces the old QVector<Parameter> wherever it was used. This encapsulates all the parameter processing and matching in the Parameters class and simplifies the code at all the places where QVector<Parameter> had been used. 3. The assignment of overload numbers is now done in the normalizeOverloads() function, which is called after all the headers and sources have been processed but before the generate phase begins. This assignment is a simple renumbering now because all the overloads of a function are linked to each other via a nextOverload_ link in the FunctionNode. The first function named qHash() is inserted into the Aggregate node's function map, but subsequent qHash() FunctionNodes are not entered into the function map but are linked to the first qHash() via its nextOverload_ link. 4. The \relates command can now be used multiple times in a single qdoc comment. There remains some work to be done here because this currently only works for global entities, but there are several cases where \relates has been used in the qdoc comment of a member of a class. This will be fixed soon, I believe. When qdoc sees the first \relates Xxx command, for example for qHash(Yyy, seed), that qHash() is a child of the global namespace. qdoc allows it to remain as a child of the global namespace but it tells class Xxx to "adopt" that child (see Node::adoptChild()). This function makes this instance of qHash() be a child of class Xxx (in this case QHash<type>), so that the parent of this qHash() becomes Xxx. After this "adoption," qHash() is a child of both the global namespace and class Xxx, but qHash() only knows it is a child of Xxx, i.e. its parent pointer is Xxx. If this is the first qHash() to become a child of Xxx, it is inserted into the function map of Xxx, but its nextOverload_ link is not changed. This is because all the global qHash() functions have already been linked into the nextOverload_ linked list, and this list must not be changed. Hence, when qdoc searches for qHash(something) to make a link to it, it will find it as a child of the global namespace, but it will correctly link to it using its actual parent pointer. When qdoc sees the second \relates Yyy for this qHash() function, qdoc sees that this FunctionNode has already been made a related non-member of Xxx, so it can't let Yyy "adopt" it. Instead, it tells Yyy to clone this qHash(), which creates a shallow copy of it but resets its nextOverload_ pointer to nullptr. I believe this clone of qHash() won't be found in a search for a function named qHash(), because the global one (the adopted one) will be found first. Or, if it is found, a link to the clone will be generated, but that's ok because the documentation is identical. Note that the existence of qHash in two child lists is taken into account at destruction time. The only place where a Node is destroyed is in the destructor of Tree, which destroys the Node tree from the root down to the leaves. Each aggregate node is responsible for deleting each of its child nodes, but it only deletes a child node if it is the parent of that child node. All of the above revealed that some of the findFunctionNode() functions were either no longer needed or weren't being called in the first place, so they were deleted. This change is now ready for testing. Change-Id: I6da3e2e9e71d39a29d90e073ed614309a49e3d4c Reviewed-by: Qt CI Bot <qt_ci_bot@qt-project.org> Reviewed-by: Paul Wicking <paul.wicking@qt.io>
* Replace nodeType() comparisons to Node:X with isX() testsMartin Smith2019-01-221-1/+1
| | | | | | Change-Id: I62692b4b667a32fe77ee9dc51be15114aae9387b Reviewed-by: Paul Wicking <paul.wicking@qt.io> Reviewed-by: Edward Welbourne <edward.welbourne@qt.io>
* Merge remote-tracking branch 'origin/5.12' into devLiang Qi2019-01-041-2/+3
|\ | | | | | | | | | | | | | | | | Conflicts: src/qdoc/htmlgenerator.cpp src/qtattributionsscanner/qdocgenerator.cpp Done-With: Martin Smith <martin.smith@qt.io> Change-Id: I56a23175579a1a699939179da2f35bbcd6c73367
| * qdoc: Fix link resolution for types under namespacesTopi Reinio2018-11-151-2/+3
| | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | When QDoc tries to resolve a link to a type from a function parameter, it sets a 'TypesOnly' find flag. For types that contain a scope resolution operator(s), i.e. double-colons, QDoc first looks for the scope (namespace), and then the type under that scope. The problem was that the TypesOnly flag was passed to also the function call to find the namespace. This failed as namespaces are not types. Another problematic corner case happened with name clashes between a C++ module and a namespace, as is the case with e.g. 'Qt3DCore'. Here, QDoc tried to resolve the module node as the scope, and subsequently failed to find anything under that scope as module nodes have no children. Task-number: QTBUG-69484 Change-Id: Ia3c8fa96263a24176a11cf23a3469a374de7973a Reviewed-by: Paul Wicking <paul.wicking@qt.io> Reviewed-by: Martin Smith <martin.smith@qt.io>
* | qdoc: Reorganize Qdoc's Node class hierarchyMartin Smith2018-10-231-508/+616
|/ | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | This is a significant refactoring of QDoc's Node class hierarchy, which is meant to make maintenance of QDoc easier, and which will enable further development of QDoc as a library and plugin. Class DocumentNode is renamed to class PageNode, and it inherits the Node base class instead of inheriting class Aggregate. Class Aggregate inherits class PageNode instead of the Node base class. IOW, class DocumentNode and class Aggregate have swapped places in the class hierarchy, and DocumentNode has changed its name to PageNode. This makes the Node hierarchy more logical because: 1. Every entity that causes a documentation page to be written is a PageNode. 2. Only those PageNodes that can have children are Aggregates. Thus the HeaderFile subtype of the former DocumentNode has been promoted to class HeaderNode, which is a subclass of Aggregate. This makes sense because the old HeaderFile DocumentNode caused a documentation page to be generated, and that documentation page was very much like a class reference page. The \headerfile command is not used a lot in the Qt documentation but there are some useful cases, so it is worth making a subclass of Aggregate to handle them. The HeaderNode is now processed very much like the ClassNode and the NamespaceNode. Developers should be advised that isDocumentNode() is now isPageNode(), but isPageNode() can no longer be used to decide if an Aggregate* is a PageNode* (DocumentNode*), because Aggregate is now a subclass of PageNode. So a new convenience function is added: isTextPageNode(), which returns true if your Node* is a PageNode but not an Aggregate. IOW, isTextPageNode() returns true if the Node* is some kind of text page that doesn't represent a C++ or QML declaration. Class ExampleNode is a subclass of PageNode, not Aggregate. IOW, an ExampleNode no longer has children. Instead, the example files and example images that belong to the example are stored as string lists. It seems to work, but there might be problems in help files I haven't found yet. Class CollectionNode is now a subclass of Node instead of LeafNode. Class LeafNode is removed. All former subclasses of LeafNode are now subclasses of Node. This change also removes a lot of DITA bitrot. Work remaining to be done: 1. Remove the remaining DITA bitrot. 2. Consider letting QmlProperty and JsProperty be instances of Property and use the Genus value to distiguish them. 3. Also consider replacing QmlPropertyGroup and JsPropertyGroup with a single PropertyGroup and use the Genus value to distinguish them. This update also rearranges the parameters passed to the clang parser, and it removes some diff conflict lines that got saved by mistake. Change-Id: I918f83030c48d96db4a5588ab53458f221a5374e Reviewed-by: Martin Smith <martin.smith@qt.io> Reviewed-by: Paul Wicking <paul.wicking@qt.io>
* Merge remote-tracking branch 'origin/5.11' into 5.12Liang Qi2018-09-111-1/+2
|\ | | | | | | | | | | | | | | Conflicts: src/macdeployqt/shared/shared.h src/qdoc/sections.cpp Change-Id: I708a20d0061e82b99ecced7d24e7a2b8c475f706
| * QDoc: Link correctly to enums as function parametersv5.11.25.11.2Paul Wicking2018-09-031-1/+2
| | | | | | | | | | | | | | | | | | | | | | Include enum type in findChildNode check, to resolve page nodes correctly. The missing check causes QDoc to not link to enums when they are function parameter types. This behavior constitutes a regression from 5.10. Task-number: QTBUG-70231 Change-Id: I57f94c08b0e207567e97127d0b7e268d90d051aa Reviewed-by: Martin Smith <martin.smith@qt.io>
* | Merge remote-tracking branch 'origin/5.11' into devFriedemann Kleint2018-07-251-11/+3
|\ \ | |/ | | | | Change-Id: I08932d5a2599831a4cc53f5a70709d7c3a27a35b
| * QDoc: Check aggregates with Node::nodeNameLessThan to improve sortingPaul Wicking2018-07-181-11/+3
| | | | | | | | | | | | | | | | | | | | | | | | | | | | Certain corner cases were not covered by the current implementation, causing the sort to fail. This change aims to make QDoc capable of sorting all nodes derived from aggregate, because an aggregate can be expected to have a user visible title that can be used to sort content alphabetically. Impressively, this has been working for most lists of classes in the generated docs, just not all. Task-number: QTBUG-67530 Change-Id: I5b5b19011c6a1e561894f8155c971da60aff7e2f Reviewed-by: Topi Reiniö <topi.reinio@qt.io> Reviewed-by: Martin Smith <martin.smith@qt.io>
* | qdoc: Document a namespace in multiple modulesMartin Smith2018-06-011-12/+73
|/ | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | qdoc didn't handle this. This update fixes most of what was wrong, but tuning the details of the namespace reference pages might follow. We have namespace Qt as an example. Most of the elements in the Qt namespace are in QtCore, but a few functions are declared in QtGui. Before this update, qdoc used the hack of using #ifdef to remove the declarations from qtextdocument.h in QtGui and .cpp and then added them back into qtnamespace.h and .cpp in QtCore. Now that hack is no longer necessary. The functions in the Qt namespace that are declared in QtGui are documented there, but the documentation is linked to from the namespace reference page, which remains in QtCore. That is, only one \namespace command is used to document the Qt namespace, and it appears in qnamespace.qdoc where it always did, but the documentation for the Qt namespace functions declared in QtGui is now appears in qtextdocument.cpp where it belongs. This also allows qdoc to report when a namespace contains elements that are public and documented, but the namespace itself is not documented, which was not possible before this change. qdoc also reports if a namespace is documented in more than one module. That is, for example, when \namespace Qt is used in both QtCore and QtGui. Note that this change will increase the number of qdoc warnings in QtBase, but the new warnings are expacted. Change-Id: If978a59209b7b2ae90713d3ae809ae03361df72f Task-number: QTBUG-67267 Reviewed-by: Martin Smith <martin.smith@qt.io>
View Lorry Controller Status