summaryrefslogtreecommitdiff
path: root/src/qdoc/clangcodeparser.cpp
Commit message (Collapse)AuthorAgeFilesLines
...
* | qdoc: Parse enum classes correctlyTopi Reinio2020-01-201-4/+5
| | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | Clang provides us sufficient information to detect a scoped enum (an enum class). For such enums, include the enum type name into the fully qualified name of the enum values. For enums related to \headerfile nodes, drop the '<Header>::' from the qualified name of the enum values as they are not valid. Ensure that this also applies to all node types in Node::plainFullName(), as including file names into a qualified path is always incorrect. In some cases, enum classes were also forward declared. This was a problem as QDoc skipped the full declaration after seeing the forward one. Combat this by re-processing the enum declarations that do not contain any values yet. Add relevant test case. [ChangeLog][qdoc] QDoc now generates correct documentation for enum classes. Fixes: QTBUG-66740 Change-Id: I36dcb3393500acb788e0a305fd0dfecc4b58ebc3 Reviewed-by: Topi Reiniö <topi.reinio@qt.io>
* | qdoc: Teach QDoc to output function and class template parametersTopi Reinio2020-01-201-7/+60
| | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | Add a visitor functor that reconstructs template parameters from the Clang AST, and use it when either a class or a method template is detected. Store this information in the node - for now, they are used only in the class reference page subtitle (for classes), and detailed section of function documentation. Template parameters are not considered when searching/linking to entities, they are for display only. [ChangeLog][qdoc] Added capability to display class/method template parameters in the generated documentation. Fixes: QTBUG-17456 Change-Id: I300cc63b9fa20d4f6efaeaa27ea3769635a7b32c Reviewed-by: Topi Reiniö <topi.reinio@qt.io>
* | qdoc: Make Config a singletonTopi Reinio2020-01-131-2/+3
|/ | | | | | | | | | | | There is no need to pass a pointer to Config throughout the API; the only instance of it is created in main() so we can turn it into a singleton. Having access to Config without API changes makes implementation of configurable features easier. Change-Id: Ida47e067865082dfe036a7a97f7f1ffc736db346 Reviewed-by: Paul Wicking <paul.wicking@qt.io>
* clang-format QDocPaul Wicking2019-12-171-118/+162
| | | | | | | | | | | | | | | | 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: Minor adjustment/cleanupPaul Wicking2019-12-111-4/+4
| | | | | | | Pre-increment instead of post-increment for efficiency and readability. Change-Id: I10b33360dd36cd1d0f4338441c1ad4724551e80e Reviewed-by: Topi Reiniö <topi.reinio@qt.io>
* QDoc: Clean up loops with iteratorsPaul Wicking2019-12-101-8/+7
| | | | | | | | | | | - 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: Ignore the 'enum' keyword when parsing a Q_PROPERTY typeTopi Reinio2019-11-141-0/+2
| | | | | | | | | | | | | | | QDoc's parsing of property types is slightly naive, in that it cannot parse a type that consists of multiple words. These are not common, but we do have a few instances of Q_PROPERTY(enum EnumName ...) in the Qt source. This commit allows QDoc to parse above properties by ignoring the string 'enum'. Fixes: QTBUG-80027 Change-Id: I3b01d463b081042dd27299c2121fafa3c99b98ce Reviewed-by: Paul Wicking <paul.wicking@qt.io>
* Merge remote-tracking branch 'origin/5.13' into devQt Forward Merge Bot2019-08-241-2/+4
|\ | | | | | | Change-Id: I43a657af3d3c5853bd062f14e3b96b87cdadea94
| * qdoc: Avoid errors related to PCH usageTopi Reinio2019-08-211-2/+4
| | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | Remove whitespace from the default parameters passed to Clang, and add '-ferror-limit=0' to disable the error limit. This helps to ensure we get a usable precompiled header on all platforms. Another issue that manifested on Windows was the order in which the (temporary) module header and the PCH was built - after writing the module header, its QFile was closed at the end of the function scope, and it received a timestamp later than the PCH. Some versions of libclang see this (rightfully) as a problem. Close the module header file handle before generating the PCH. Task-number: QTBUG-75053 Change-Id: I61d066c40eddfdfdcc4c8cd847f6bec40652f9e0 Reviewed-by: Paul Wicking <paul.wicking@qt.io>
* | QDoc: Extract helper functions from Generator to UtilitiesPaul Wicking2019-08-091-1/+2
| | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | 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-37/+37
| | | | | | | | | | | | | | | | | | | | | | 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>
* | QDoc: Clean up includes in Generator and ClangCodeParserPaul Wicking2019-07-301-9/+11
| | | | | | | | | | | | | | 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-161-11/+14
|\ \ | |/ | | | | Change-Id: I51fa8c90923e9730d7787e763fad996db51d350e
| * qdoc: Correct algorithm for finding class qualifierMartin Smith2019-07-111-11/+14
| | | | | | | | | | | | | | | | | | | | | | The algorithm for finding the class qualifier for the function name in a \fn signature was incorrect in cases where the return type also had a class qualifier. This resulted in some clang error messages being printed when they should not have been printed because the class was marked internal. This update corrects that algorithm. Change-Id: I02983710c73251b8fc75ccb2893ae1d9f5aa0fe6 Reviewed-by: Paul Wicking <paul.wicking@qt.io>
* | Merge remote-tracking branch 'origin/5.13' into devQt Forward Merge Bot2019-07-111-51/+60
|\ \ | |/ | | | | | | | | | | Conflicts: .qmake.conf Change-Id: If0d8f3f1dc3be742bb2fadb7873eabdd6f46d3d1
| * Merge remote-tracking branch 'origin/5.13.0' into 5.13Liang Qi2019-07-021-51/+60
| |\ | | | | | | | | | | | | | | | | | | | | | Conflicts: src/qdoc/clangcodeparser.cpp Done-With: Topi Reiniö <topi.reinio@qt.io> Change-Id: I343d2ae6ab3a381756c4476c7f3f5ba0212ad43c
| | * qdoc: Don't log guessed include pathsv5.13.0-rc3v5.13.05.13.0Martin Smith2019-06-111-13/+1
| | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | A complaint about excessive logging was received because of the logging of each guessed include path when qdoc is not given any include paths at all. This update removes the logging of those lines and changes the remaining single log line to: No include paths passed to qdoc; guessing reasonable include paths Task-number: QTBUG-76204 Change-Id: I000ee7959f00f654e750ac1b68a0c2b6dcccd472 Reviewed-by: Fabian Vogt <fabian@ritter-vogt.de> Reviewed-by: Paul Wicking <paul.wicking@qt.io> (cherry picked from commit 8e3c53a196f66a1c9a370cda1dfde51792f92364) Reviewed-by: Martin Smith <martin.smith@qt.io>
| | * qdoc: Fix regressions in include path handlingTopi Reinio2019-06-071-54/+61
| | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | Commit 50a172f8 broke the way QDoc parses include paths passed from qdocconf files by always prepending them with '-I'. While this ensured that Clang uses them as include paths, QDoc no longer found module headers local to the documentation project as '-I/path/to/module' is never a valid file system path. This change fixes the issue and removes duplicated and unnecessary code. Fixes: QTBUG-76279 Change-Id: I7006000ec6be823afd10bae59eb88780ccf32b23 Reviewed-by: Martin Smith <martin.smith@qt.io> Reviewed-by: Paul Wicking <paul.wicking@qt.io>
| | * qdoc: Accept include paths without -IMartin Smith2019-06-041-2/+13
| | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | This update lets qdoc accept include paths with or without the -I and with or without a space between the -I and the path. Without the space is preferred. Task-number: QTBUG-74675 Change-Id: I4a1dcc04a3c9a6586e24b50bccf0f1f37d02ed4c Reviewed-by: Paul Wicking <paul.wicking@qt.io> (cherry picked from commit e33ac6f1b1ebb882684f24f7d026267584d9393a)
| | * qdoc: Drop '-I' prefix from module header pathv5.13.0-rc1Topi Reinio2019-05-241-0/+2
| | | | | | | | | | | | | | | | | | | | | | | | | | | | | | Under certain conditions the '-I' prefixes survive in the list of resolved include paths. Fixes: QTBUG-76026 Change-Id: Ie3543b5aa8b88d8021175b3168ab8de8a4497878 Reviewed-by: Martin Smith <martin.smith@qt.io> Reviewed-by: Paul Wicking <paul.wicking@qt.io>
* | | qdoc: Remove hard-coded -fno-exceptions Clang optionTopi Reinio2019-07-031-1/+0
| | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | This was a workaround for http://reviews.llvm.org/D17988 that has now been fixed. This commit enables exception support for code parsed by QDoc. If required, the option can still be defined using 'clangdefines' qdocconf variable. Task-number: QTBUG-76795 Change-Id: I010293b25fb7833a267a6a488cbe94a477352664 Reviewed-by: Martin Smith <martin.smith@qt.io> Reviewed-by: Michael Vlach <vlach.michael@gmail.com>
* | | Fix translation unit debug output for parseFnSimon Hausmann2019-06-281-1/+1
|/ / | | | | | | | | | | | | | | | | parseFn() uses its own arguments vector (args), which is passed to clang_parseTranslationUnit2 and that's also what should be printed in the debug output. Change-Id: Ib8be035203aa3887fc79d0695e846e9b2924a191 Reviewed-by: Martin Smith <martin.smith@qt.io>
* | qdoc: Build artificial module headerMartin Smith2019-06-071-35/+48
| | | | | | | | | | | | | | | | | | | | | | | | | | | | This update lets qdoc build an artificial module header whenever it can't find the project's module header. The artificial module header contains a #include "/absolute/path/header.h" for each header found using the project's headerdirs and headers variables in the qdocconf file. header files with names ending in _p.h are not included in the artificial module header. The ordering of the includes in the artificial module header is not controlled, so the includes must not be order-dependent. Task-number: QTBUG-76005 Change-Id: I9d0975c571b29e0c3c5972a4e1f78427c595d52d Reviewed-by: Paul Wicking <paul.wicking@qt.io>
* | qdoc: Don't log guessed include pathsMartin Smith2019-06-071-13/+1
| | | | | | | | | | | | | | | | | | | | | | | | | | A complaint about excessive logging was received because of the logging of each guessed include path when qdoc is not given any include paths at all. This update removes the logging of those lines and changes the remaining single log line to: No include paths passed to qdoc; guessing reasonable include paths Task-number: QTBUG-76204 Change-Id: I000ee7959f00f654e750ac1b68a0c2b6dcccd472 Reviewed-by: Fabian Vogt <fabian@ritter-vogt.de> Reviewed-by: Paul Wicking <paul.wicking@qt.io>
* | qdoc: Accept include paths without -IMartin Smith2019-05-311-2/+13
|/ | | | | | | | | | This update lets qdoc accept include paths with or without the -I and with or without a space between the -I and the path. Without the space is preferred. Task-number: QTBUG-74675 Change-Id: I4a1dcc04a3c9a6586e24b50bccf0f1f37d02ed4c Reviewed-by: Paul Wicking <paul.wicking@qt.io>
* qdoc: Turn off clang errors in PCH build without include pathsMartin Smith2019-04-081-3/+18
| | | | | | | | | | | | | | | | When the build system can't pass qdoc the include paths to qdoc, qdoc tries to guess reasonable include paths. There has been one case running qdoc on macOS for the QtPlatformHeaders module, where qdoc must try to guess the include paths. The guessed paths are not sufficient, and clang prints a large number of errors caused by missing stuff. This change tells clang not to report errors during the PCH build if qdoc had to guess the include paths. qdoc reports in its log that it guessed the include paths and that it turned off the clang error reporting. Change-Id: I91a4242dcc7d3017d511d969621cc3d673c47963 Reviewed-by: Paul Wicking <paul.wicking@qt.io>
* qdoc: Search for QML type before creating itMartin Smith2019-04-021-3/+3
| | | | | | | | | | | | | | | | | | | | 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: Correct ref pages for inner classesMartin Smith2019-02-081-17/+24
| | | | | | | | | | | | | | | | | | | | | | 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-35/+46
| | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | 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>
* qdoc: Do not print error for future functionsMartin Smith2018-12-031-6/+22
| | | | | | | | | | | | | | | | | | | Some function declarations are marked as not existing until Qt 6.0 in both the .h and .cpp files, but they are documented in the .cpp file. qdoc can't tie the documentation for these functions to their declarations because of the way clang is used, and qdoc reports that reports the documentation as an error. This update let's qdoc ignore these functions and not print the error when they are marked with \since 6.0. This will also work with other future versions. This update also collects all the uses of #define COMMAND_xxx in one location, which was partially required by the \since 6.0 change. Change-Id: I55052359f387406da340c748768f8e76c0b39d53 Reviewed-by: Paul Wicking <paul.wicking@qt.io> Reviewed-by: Topi Reiniö <topi.reinio@qt.io>
* qdoc: Correct clang resource path argumentMartin Smith2018-11-281-3/+2
| | | | | | | | | The construction of this argument had been modified incorrectly. This update corrects it. Change-Id: I59dc6cc0e5b12fd347f778ea4fc78e00d9c42d89 Reviewed-by: Paul Wicking <paul.wicking@qt.io> Reviewed-by: Martin Smith <martin.smith@qt.io>
* qdoc: Accept all #include lines in module headerMartin Smith2018-10-231-17/+13
| | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | qdoc was building a temporary module header by copying in the actual module header and then following it with includes for all the private headers in the module's private include directory. But this attempt to include headers that end in "_p.h" didn't include any headers at all, so that code is removed in this update. The problem with just copying the entire module heaqder into the temporary module header was that some of the #include lines that qdoc needed to see were not parsed by clang because they were surreounded by #if QT_CONFIG(feature) if the feature wasn't present for the Qt build. Instead of copying the module header to the tempory module header, this update changes it to read the module header line by line and write each #include to the temporary module header, including the ones that are surrounded by QT_CONFIG(feature): _#if QT_CONFIG(dtls) _#include "qdtls.h" _#endif This reduces the qdoc error count, but the example above causes a static assert when the dtls feature is not present. So this must be added as well: _#ifndef Q_CLANG_QDOC QT_REQUIRE_CONFIG(dtls); _#endif Change-Id: I7fe26b5b714d41654a2cfdda19b8fe4b31999b91 Reviewed-by: Martin Smith <martin.smith@qt.io> Reviewed-by: Paul Wicking <paul.wicking@qt.io>
* qdoc: Let qdoc print better log messagesMartin Smith2018-10-231-17/+24
| | | | | | | | | | | | | | | | | | | | | | | | | | | | | This change enables qdoc to print better log messages. A new logging function is added to Location, where the qdoc error and warning functions are located. The new function is logToStdErrAlways(msg). It always formats msg for output to stderr by prepending the current time and the word LOG. Several LOG messages are now sent to stderr. Also, qdoc now always tells clang to output its parsing errors to stderr during the building of the precompiled header in the prepare phase. These clang parser errors are easily identified in the new LOG. When no include paths are passed to qdoc on the command line, which is the case for QtPlatformHeaders, qdoc guesses some reasonable include paths from the information available and passes them to clang. It works ok for the QtPlatformHeaders module. However, clang gets lost in some NSOpenGL headers and prints quite a lot of useless parse errors, so we arbitrarily turn off clang's parse errors whenever qdoc has to guess the include paths. The guessed include paths are printed in the LOG, and a warning that clang does not print parse errors when the include paths are guessed is also printed in LOG. Change-Id: I8e5bd0cc5b27463c4c85c9cdcc01b030ac03a1c1 Reviewed-by: Martin Smith <martin.smith@qt.io> Reviewed-by: Paul Wicking <paul.wicking@qt.io>
* qdoc: Reorganize Qdoc's Node class hierarchyMartin Smith2018-10-231-10/+13
| | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | 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>
* QDoc: Clean up code, old style casts and more 0 nullptr constantsPaul Wicking2018-09-031-10/+10
| | | | | Change-Id: I96ff2ba00f419796a8649d5392f7c164579b0d16 Reviewed-by: Martin Smith <martin.smith@qt.io>
* qdoc: Document a namespace in multiple modulesMartin Smith2018-06-011-1/+1
| | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | 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: Combine anonymous enumsv5.11.0-beta3Martin Smith2018-04-041-4/+13
| | | | | | | | | | When multiple anonymous enum types appear in the same class declaration, merge them into one enum type called "anonymous" in that class. Change-Id: Iccdbec5c54948e5e61a7025d84dedaed1be3e76b Task-number: QTBUG-67243 Reviewed-by: Leena Miettinen <riitta-leena.miettinen@qt.io>
* qdoc: Distinguish between undefined and defined-as-empty config varsTopi Reinio2018-03-281-1/+1
| | | | | | | | | | | | | | | | Make Config::getString() return an empty string for variables that are defined as empty, while continuing to return a null string for undefined ones. Use a defined-as-empty 'moduleheader' variable: moduleheader = to mark a documentation project that doesn't need a precompiled header to be built. Change-Id: I2ccb631c73a1b91dc35955e5f21648db88915064 Reviewed-by: Martin Smith <martin.smith@qt.io>
* qdoc: Fix Pyside2 documentation builds for shadow buildsFriedemann Kleint2018-03-151-9/+21
| | | | | | | | | Match interesting headers by file names in case mismatches occur between installed headers and headers in the source tree. Task-number: PYSIDE-620 Change-Id: Ie36fbd46fda38c86d88a00a992cac2fb58dd76bc Reviewed-by: Martin Smith <martin.smith@qt.io>
* qdoc: Remove -fPIC from default options when Q_OS_WINMartin Smith2018-03-121-1/+3
| | | | | | | | | This update only adds -fPIC to the options passed to clang if Q_OS_WIN is not defined. Change-Id: I473ac14a026aecff141ab6d16e6283efe7bc5bd5 Reviewed-by: Leena Miettinen <riitta-leena.miettinen@qt.io> Reviewed-by: Topi Reiniö <topi.reinio@qt.io>
* qdoc: Canonicalize include pathsTopi Reinio2018-03-061-0/+9
| | | | | | | | | | | | | | | | Resolve canonical include paths from the ones passed to QDoc from the command line and .qdocconf variable 'includepaths'. This allows adding include paths that are relative to the documentation project (.qdocconf file): includepaths = -I . which is useful for modules where we do not have a complete set of include paths provided by qmake. Change-Id: Ieaf0816e8c26857c873e4b521164c70bb1f5e5b3 Reviewed-by: Martin Smith <martin.smith@qt.io>
* qdoc: Fix bugs in resolving inheritance and finding overridden functionsMartin Smith2018-02-231-5/+38
| | | | | | | | | | | | | | | | | | | | | 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: Add Q_FALLTHROUGH() to clangcodeparser.cppFriedemann Kleint2018-02-191-0/+1
| | | | | | | Silence warning by gcc 7.2. Change-Id: Ia734d7161fccb2f700bd955dc52c904e1e31987e Reviewed-by: Martin Smith <martin.smith@qt.io>
* qdoc: Ensure that override attribute is saved in index filesMartin Smith2018-02-081-0/+2
| | | | | | | | | The ClangCodeParser was not setting the override flag in function nodes for member functions declared with the override attribute. This update fixes that bug. Change-Id: Ib67c106982f83164a862b2181c77798733fc3864 Reviewed-by: Topi Reiniö <topi.reinio@qt.io>
* qdoc: Hide clang errors for \fn commands in prepare phaseMartin Smith2018-02-051-1/+1
| | | | | | | | | | | | When clang parsing errors were detected in the prepare phase, they were being printed without the preceding qdoc warning that shows where they occur in the source file. The qdoc warning was not printed because qdoc was running in the prepare phase, but the clang errors were printed, and that was wrong. This update ensures that the clang parsing errors are only printed in the generate phase (or in singleexec mode). Change-Id: I011fa06626a5e9930fde329113d2bbac8830473b Reviewed-by: Topi Reiniö <topi.reinio@qt.io>
* qdoc: Switch Clang index generation verbose when logging is enabledFriedemann Kleint2018-02-011-1/+2
| | | | | Change-Id: If42398de185eb820d9880173b4e67a0b203e2f60 Reviewed-by: Martin Smith <martin.smith@qt.io>
* qdoc: Delay ignoring of qt_xxx names until outputMartin Smith2018-01-311-2/+0
| | | | | | | | | | | | | | 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-1/+28
| | | | | | | | | | | | | 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: Remove test that skipped parsing \fn commands in prepare phaseMartin Smith2018-01-261-2/+0
| | | | | | | | | | | | | | It was thought unnecessary to parse the \fn commands during the prepare phase, but it is required to determine whether the functions should be marked internal and private. Without parsing the \fn commands during the prepare phase, the documentation can't be assigned to the function, so it looks like it is undocumented and is marked internal and private in the index file. That was wrong, so now qdoc calls clang to parse the \fn commands, even during the prepare phase. Unfortunately, this slows qdoc by a significant amount. Change-Id: I51ab621bb9d4ffff0a245d3a842d6e7b4558ca84 Reviewed-by: Martin Smith <martin.smith@qt.io>
View Lorry Controller Status