summaryrefslogtreecommitdiff
path: root/src/qdoc/generator.cpp
Commit message (Collapse)AuthorAgeFilesLines
...
* | QDoc: minor cleanup in Generator and NodePaul Wicking2019-10-031-8/+4
| | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | 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: Minor cleanup in generator.cppPaul Wicking2019-10-011-5/+5
| | | | | | | | | | | | | | | | | | | | Fix 0 as nullptr constant. Stop using C-style casts: - Do not cast to int that which returns an int (QString::length()) - Use static_cast<>() where it's sensible to do so. Change-Id: I48c7a3e6f1465759dd3973eff66656a4f2a1c19a Reviewed-by: Edward Welbourne <edward.welbourne@qt.io>
* | QDoc: Use range-based for instead of foreachPaul Wicking2019-09-281-13/+14
| | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | 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>
* | QDoc: Remove unused code in generator.cppPaul Wicking2019-09-271-2/+0
| | | | | | | | | | | | Change-Id: Ib3e66cc21ba5f96b5e8b35d6021d643317bd961d Reviewed-by: Martin Smith <martin.smith@qt.io> Reviewed-by: Edward Welbourne <edward.welbourne@qt.io>
* | Merge remote-tracking branch 'origin/5.13' into 5.14Qt Forward Merge Bot2019-09-271-44/+82
|\ \ | |/ | | | | Change-Id: I5c06b3e0177fcccd988620ab269f75632689a54c
| * qdoc: WebXML output format: Fix issues with example pagesTopi Reinio2019-09-261-44/+81
| | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | Since QDoc no longer stores example files as nodes in its tree, the WebXMLGenerator failed to generate output for those files. Fix this by generating those pages explicitly as needed, overriding functions from the Generator base class. Prevent QDocIndexFiles from writing nested <page> elements when WebXMLGenerator is in use, as that does not work as expected with shiboken2. Fixes: PYSIDE-1088 Change-Id: I01c2af2391726f448271fdb810ffc3da923caca5 Reviewed-by: Venugopal Shivashankar <Venugopal.Shivashankar@qt.io> Reviewed-by: Paul Wicking <paul.wicking@qt.io>
| * qdoc: Fix issues with related non-membersTopi Reinio2019-09-201-0/+1
| | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | 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: Extract helper functions from Generator to UtilitiesPaul Wicking2019-08-091-22/+0
| | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | This change adds a new Utilities namespace to QDoc. This namespace holds QDoc-internal utility methods. The first few methods are debugging methods extracted from Generator::. Generator is then changed to make use of the same methods from Utilities. As a concequence of this, Utilities is also introduced to ClangCodeParser and main. This enables further refactoring of several classes, including the QDocCommandLineParser class. The purpose is to clarify dependencies and reduce entanglement, so that QDoc's classes become easier to test. Task-number: QTBUG-71176 Change-Id: I5838fc2d933f78db682cb6e4755d31bb48175fcb Reviewed-by: Edward Welbourne <edward.welbourne@qt.io>
* | QDoc: Clean up whitespacePaul Wicking2019-08-081-69/+69
| | | | | | | | | | | | | | | | | | | | | | 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>
* | QDoc: Ensure all includes are uniform and according to stylePaul Wicking2019-08-031-2/+2
| | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | 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-2/+1
|\ \ | |/ | | | | Change-Id: Id63def71d27afe593d991478ebc44b7052194e47
| * qdoc: Fix "Inherited By" outputMartin Smith2019-07-311-2/+1
| | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | 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>
* | QDoc: Clean up includes in Generator and ClangCodeParserPaul Wicking2019-07-301-3/+6
| | | | | | | | | | | | | | Change-Id: I58b27c40b68dd1c00294d2f9a362eb99b7285032 Housekeeping: Make includes according to style. Reviewed-by: Jędrzej Nowacki <jedrzej.nowacki@qt.io> Reviewed-by: Martin Smith <martin.smith@qt.io>
* | Merge remote-tracking branch 'origin/5.13' into devQt Forward Merge Bot2019-07-231-3/+18
|\ \ | |/ | | | | Change-Id: I6583a8d818ef437d24384c63683da7669cd62d87
| * qdoc: Fix the \reimp command outputMartin Smith2019-07-221-3/+18
| | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | 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>
* | Merge remote-tracking branch 'origin/5.13' into devQt Forward Merge Bot2019-06-111-2/+5
|\ \ | |/ | | | | Change-Id: If7cf7604d1ead1cd1f9980a05ada6d2aa1de0dbf
| * qdoc: Ensure Generator::fullDocumentLocation() returns a non-empty stringTopi Reinio2019-06-031-2/+5
| | | | | | | | | | | | | | | | | | | | | | | | The function took the parent node's location without checking whether the parent is the root namespace. For example nodes (and possibly others), this meant that we got an empty location. This in turn resulted in QDoc omitting the 'href' attribute when writing an .index node entry for an example node, and consequently, linking failures. Fixes: QTBUG-76171 Change-Id: I984ada1b88468aab71d08ba7d102bd8661304dab Reviewed-by: Martin Smith <martin.smith@qt.io>
* | Fix deprecation warnings about deprecated container conversionsFriedemann Kleint2019-05-231-1/+2
|/ | | | | | | | | 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-5/+4
| | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | 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: Allow replacing file lists on \example pages with a link to a URLv5.13.0-beta2Topi Reinio2019-04-091-1/+52
| | | | | | | | | | | | | | | | | | Source and image file lists that are automatically generated at the end of example pages have outlived their usefulness, at least for Qt docs. When browsing example documentation offline via Qt Creator's Help, the user has typically already opened the example project. For online documentation, a better option is to link to a remote repository where the user can browse the example's content. This commit adds a new configuration variable 'url.examples' - if defined, file listings are omitted and a link is constructed for each example based on the parameter passed to the \example command and the 'examplesinstallpath' configuration variable. Task-number: QTBUG-74391 Change-Id: If1f76ee34c5e50236fae626f251e00bf24c1045d Reviewed-by: Martin Smith <martin.smith@qt.io>
* qdoc: Search for QML type before creating itMartin Smith2019-04-021-5/+5
| | | | | | | | | | | | | | | | | | | | 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-15/+3
| | | | | | | | | | | | | | | 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: Make timestamps in LOG lines opt inMartin Smith2019-03-191-0/+1
| | | | | | | | | | | | | | | | Beginning in 5.13, qdoc prints log lines in the the qdoc warning and error output that tell the reader what qdoc is doing. These can help the reader quickly see where qdoc is working when it prints warnings and errors. Each LOG line also included a timestamp, which was useful for measuring how much time qdoc was using in each phase of each module. But these timestamps made diffing sequential log files difficult, so the timestamps are now removed. They can be enabled for debugging qdoc by adding -timestamps to the qdoc commandline. Change-Id: I55ae24e642757eed2cb57028bd22626b6efc82f9 Reviewed-by: Friedemann Kleint <Friedemann.Kleint@qt.io> Reviewed-by: Martin Smith <martin.smith@qt.io>
* QDoc: Code cleanup, use nullptr for nullptr constantsPaul Wicking2019-02-081-14/+14
| | | | | | | | | | 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: generate proper html for example source file pagesPaul Wicking2019-02-081-10/+1
| | | | | | | | | | Source for examples are put into html files that are linked to from the example page. In 5.12 these html files contained the doc site header, footer, and proper styling. This behavior is restored with this change. Change-Id: I23254366e4f85d348ed1bf7af5175334920cd672 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-3/+9
| | | | | | | | | | | | | | | | | | | | | | 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: Fix links to images used in examplesPaul Wicking2019-02-081-1/+2
| | | | | Change-Id: I2603288d8baed5574ffb8d199b96e0c42672c0d4 Reviewed-by: Martin Smith <martin.smith@qt.io>
* qdoc: Major clean-up of FunctionNode and parameter processingv5.13.0-alpha1Martin Smith2019-02-061-131/+106
| | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | 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>
* Inline various simple methods in QDocMartin Smith2019-01-231-26/+0
| | | | | Change-Id: Ie2ea694bd319f483e9a70f5934031028e0894976 Reviewed-by: Paul Wicking <paul.wicking@qt.io>
* Replace nodeType() comparisons to Node:X with isX() testsMartin Smith2019-01-221-8/+7
| | | | | | Change-Id: I62692b4b667a32fe77ee9dc51be15114aae9387b Reviewed-by: Paul Wicking <paul.wicking@qt.io> Reviewed-by: Edward Welbourne <edward.welbourne@qt.io>
* Fix bug where -module part of module-page-names were lostMartin Smith2019-01-221-17/+13
| | | | | | | | | | The module-pages lost the "-module" part of their file-names, which meant all the links to them changed. This regression caused diffs in our docs which we'd rather not have. Change-Id: I9b8bfa93cab1e359c417cabe409110601747c060 Reviewed-by: Paul Wicking <paul.wicking@qt.io> Reviewed-by: Topi Reiniö <topi.reinio@qt.io>
* Kill some dead code; it was all #if 0 beforeMartin Smith2019-01-221-85/+0
| | | | | | Change-Id: I1981a9259175098e5a9eec601bc28282ef2da82e Reviewed-by: Paul Wicking <paul.wicking@qt.io> Reviewed-by: Topi Reiniö <topi.reinio@qt.io>
* qdoc: Reorganize Qdoc's Node class hierarchyMartin Smith2018-10-231-182/+288
| | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | 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: Restore the correct output directory for example imagesTopi Reinio2018-08-281-1/+2
| | | | | | | | | | | | | | | | | | | | Commit ef5dc9d4 introduced a regression where the images used in examples are not copied to the correct output directory. Task-number: QTBUG-70218 Change-Id: I2a1b8a48e9b956e0f6dcc3318abc8b6400eb19e0 Reviewed-by: Paul Wicking <paul.wicking@qt.io> Reviewed-by: Friedemann Kleint <Friedemann.Kleint@qt.io>
* | Merge remote-tracking branch 'origin/5.11' into devLiang Qi2018-06-301-7/+5
|\ \ | |/ | | | | | | | | | | Conflicts: src/androiddeployqt/main.cpp Change-Id: I3df907e197b1b976f74562f1a9cce10261f166f3
| * qdoc: Remove 'QML' specifier from generated type stringsTopi Reinio2018-06-221-7/+5
| | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | \since command for QML properties generates a string 'This QML property was introduced in Qt x.y' This commit drops the use of QML from above sentence. There's little need to repeat the string 'QML' as it appears on QML reference page already - by keeping the type strings simple, the generated sentences make more sense also when commands like \qmlproperty are used in documenting a non-QML interface, as is the case with Qbs. Task-number: QBS-1294 Change-Id: I9c8488331b3fb279f80aeb390b00e48b12d79e19 Reviewed-by: Martin Smith <martin.smith@qt.io> Reviewed-by: Christian Kandeler <christian.kandeler@qt.io>
* | qdoc: Refactor section construction and processingMartin Smith2018-06-011-19/+0
| | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | This update adds two classes called Section and Sections. These classes replace the FastSection and Section structs that used to be in codemarker.h, and they also replace the section building functions that used to be in codemarker.cpp and cppcodemarker.cpp. Basically, the two structs FastSection and Section are combined into the single new class Section. FastSection was used to collect all the members for a section in a map with the node names as the keys and the nodes as the values. This allowed the names to be sorted as the map is built. When completed, themap was used to build the Section, where the map keys were copied to a list in the Section, and the map values were copied to another list. The values in these lists were already sorted. Then the Section structs were copied into a list of Sections and the list was returned. The code was becoming too messy to maintain and impossible to use for implementing custom sections for QTBUG-45725. Now the new class Section combines the deleted structs FastSection and Section. The procedure for building an instance of class Section is much the same as the old procedure for building a struct FastSection and then using the FastSection to build a struct Section. In the old procedure, 4 separate passes over all the child nodes of a class were required to build the FastSections and Sections for the Summay lists, the Details lists, the All Members list, and the Obsolete members lists. In the new procedure, only a single pass is required. This single pass is the purpose for the other new class Sections, which manages several static instances of QVector<Section>. All the required Section objects are built at the same time, and the never have to be copied. When the docs for a class, namespace, etc have been written, each Section is cleared but not deleted. The static instances of QVector<Section> are kept in their constructed state. I thought this would speed up qdoc some, because there is much less allocating and deallocating of objects, but it seems to have actually slowed down a bit, and I can't see why. But the code is a lot simpler and reusable for the custom sections proposal, so I will continue with it and hopefully find the cause of the slowdown. Change-Id: I49f592c631ccc6182d1dae742985c7b2bb15c81b Reviewed-by: Martin Smith <martin.smith@qt.io>
* | qdoc: Remove support for \compat commandMartin Smith2018-06-011-26/+1
| | | | | | | | | | | | | | | | | | The \compat command is no longer needed in QDoc, and the code that supports it makes some parts of QDoc needlessly complex. This update removes it, along with the documentation for it in the QDoc manual. Change-Id: I249b571e24ff8c3530d1ae5dbb4fff9186dba49d Reviewed-by: Martin Smith <martin.smith@qt.io>
* | qdoc: Document a namespace in multiple modulesMartin Smith2018-06-011-6/+12
|/ | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | 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>
* qdoc: Don't output undocumented functions from Q_OBJECTMartin Smith2018-03-011-18/+1
| | | | | | | | | | | | | Earlier, a test was added to qdoc to ensure that functions added to class declarations by macros like Q_OBJECT would not cause qdoc to output warnings that the functions were not documented. But the undocumented functions were still listed in the documentation. This update keeps them out of the documentation. Task-number: QTBUG-66742 Change-Id: I10014341fc7b870ef937ef7f0a303ccc301bf8b5 Reviewed-by: Leena Miettinen <riitta-leena.miettinen@qt.io> Reviewed-by: Topi Reiniö <topi.reinio@qt.io>
* qdoc: Fix bugs in resolving inheritance and finding overridden functionsMartin Smith2018-02-231-13/+14
| | | | | | | | | | | | | | | | | | | | | A class node must have pointers to the class nodes of its base classes, but these pointers might not exist when qdoc creates the class node for the class. They might not exist until all the index files and include files have been parsewd. qdoc was trying to resolve the base classes too early. This update lets qdoc wait until it is known that everything has been built before attempting to resolve inheritance. This update also delays finding the pointer to the function node for the overridden function for a function marked "override" until the pointer is needed. Instead of storing the pointer to the node, the qualification path to the function is stored as a string, and the string is used to look up the overridden function when it is needed, which is only when the \reimp command is processed during output. The function that resolves the pointer to the overridden function was moved to the function node class, where it makes more sense. The way a few qdoc warnings are reported was also changed. Change-Id: Ia54642d11242386ae75139065f481e5d30f79fb5 Reviewed-by: Topi Reiniö <topi.reinio@qt.io>
* qdoc/Config::findFile() Make userFriendlyFilePath an optional out parameterv5.11.0-alpha1Friedemann Kleint2018-02-141-3/+2
| | | | | | Task-number: PYSIDE-363 Change-Id: If076c9a77a5a11c05035f6fc30e6d68e60a35045 Reviewed-by: Martin Smith <martin.smith@qt.io>
* Merge remote-tracking branch 'origin/5.10' into 5.11Liang Qi2018-02-121-0/+4
|\ | | | | | | Change-Id: I1b23f25c7add7a9bcb97c91696bea58a8f9c3b42
| * Merge remote-tracking branch 'origin/5.9' into 5.105.10Liang Qi2018-02-021-0/+4
| |\ | | | | | | | | | | | | | | | | | | Conflicts: src/qtattributionsscanner/main.cpp Change-Id: Ic509d457547ec64122b17511563de5ea3e1b1b44
| | * qdoc: Handle Module, QmlModule nodes in Generator::typeStringKai Koehne2018-01-241-0/+4
| | | | | | | | | | | | | | | | | | | | | Fixes output of \since, \preliminary if associated with a module. Change-Id: I760963135283d4978225e2ad72f3c0c6df852e56 Reviewed-by: Martin Smith <martin.smith@qt.io>
* | | qdoc: Delay ignoring of qt_xxx names until outputMartin Smith2018-01-311-5/+6
| | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | The ignoreSymbol() function in class ClangVisitor was told to return true for every name that starts with "qt_". This was too aggressive, so the test is now done at output time. If a function name that starts with "qt_" has no documentation, qdoc does not warn with "No documentation for qt_..." because almost all such names are not to be documented. But they can be documented, so that's why the test is performed at the last moment. Change-Id: I2f322bed32dcae43336ead0735490560190d8095 Reviewed-by: Topi Reiniö <topi.reinio@qt.io>
* | | qdoc: Add a logging categoryFriedemann Kleint2018-01-311-12/+13
| | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | Remove the debug functionality from the Generator class and add a logging category instead. Add some debug statements outputting the command line arguments and clang arguments. This makes it possible to obtain logging output by setting for example QT_LOGGING_RULES=qt.qdoc.debug=true . Task-number: PYSIDE-363 Change-Id: I3ecfe548e14aa3e2d03f19d07fc61a2647b75111 Reviewed-by: Martin Smith <martin.smith@qt.io>
* | | qdoc: Fix handling of shared comment nodes in generate phaseMartin Smith2018-01-261-2/+2
| | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | Shared comments nodes were not detected and handled correctly in certain cases. This update fixes those problems to avoid trying to output documentation for the individual nodes, when they are sharing a comment. Only the shared comment node should cause documentation to be generated for the nodes sharing the comment. Change-Id: I4ad7afc0964b1b6836dd5a140aa874784974b139 Reviewed-by: Martin Smith <martin.smith@qt.io>
* | | qdoc: Avoid qdoc warning for undocumented d_func()Martin Smith2018-01-171-6/+9
| | | | | | | | | | | | | | | | | | | | | | | | | | | | | | Two d_func() functions are declared by the Q_DECLARE_XXX macros, but they are normally not documented. This update adds the name to the list of functions that need not be documented. Change-Id: I6e8227da015720a3f8771e43f5e7e7b29a843a33 Reviewed-by: Topi Reiniö <topi.reinio@qt.io>
View Lorry Controller Status