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>

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>

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>

Silence warning by gcc 7.2.

Change-Id: Ia734d7161fccb2f700bd955dc52c904e1e31987e
Reviewed-by: Martin Smith <martin.smith@qt.io>

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>

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>

Change-Id: If42398de185eb820d9880173b4e67a0b203e2f60
Reviewed-by: Martin Smith <martin.smith@qt.io>

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>

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>

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>

old header.LGPL21 was used in few src files. Replace those with correct
header.LGPL one

Change-Id: I8333e14f89bd8175c98db6c60803c7c131448cbc
Reviewed-by: Topi Reiniö <topi.reinio@qt.io>

These functions were being eliminated from the documentation in
the clang visitor, but this doesn't when the functions actually
have documentation. This update moves the test for whether they
should be documented or not to the Generator class.

This update also avoids reporting a qdoc warning for a typedef
defined in Q_GADGET.

Change-Id: Icca7297ec2123c684203d225d2bda96e50dacd8c
Reviewed-by: Topi Reiniö <topi.reinio@qt.io>

From time to time, we have classes added that are marked both
\internal and \preliminary in their \class comment. This was a
race condition that set the status of the class documentation
to either internal or preliminary depending on the order of the
\internal and \preliminary commands. But \preliminary should
only be used when the class is meant to be included in the public
API marked as preliminary, so users will understand that it might
be changed before it is stable. So this update lets \internal win
when both commands appear in the \class comment, regardless of
their order.

This update also prevents clang parsing errors from being reported
for \fn commands where the class containing the member function is
marked \internal. This eliminates a lot of qdoc warnings.

Change-Id: Id1ecec4bdd573ae81fa5d589dfdd4afc4b313825
Reviewed-by: Topi Reiniö <topi.reinio@qt.io>

Because processing these commands do not use clang, their implementation
is moved from ClangCodeParser to CppCodeParser - this ensures
that these topic commands are processed also when they appear in
.qdoc files (PureDocParser, used for .qdoc, derives from CppCodeParser).

Also, these functions did nothing when qdoc was running in prepare
phase which in turn meant that they were not written to .index, thus
breaking cross-module linking for macros/QML methods/signals. That
check is now removed and the functions always do their thing.

Change-Id: I8d9333b02092708955b619b573254eda5d82f038
Reviewed-by: Martin Smith <martin.smith@qt.io>

The shared comment in qdoc was originally meant only for
use with the \fn command, and only for multiple \fn commands
in the same class. But it proved to be useful for other things,
so people started using it in other contexts, even though it
didn't work there. This update should handle them all.

For example, when listing multiple \fn commands, they no longer
need be for functions in the same class. Also, multiple \typedef
commands are handled correctly.

Change-Id: I4be86026a227d74822f5f2295577adf0fe170d49
Reviewed-by: Martin Smith <martin.smith@qt.io>

This update lets clang report to qdoc whenever Q_INVOKABLE
appears in a C++ function declaration so that qdoc can add
a note to the function's documentation telling the reader
that the function is invokable via the meta-object system
and from QML.

Task-number: QTBUG-59083
Change-Id: I9b62ba1c9159a1ec43c6a59e576efdb71bff62e5
Reviewed-by: Martin Smith <martin.smith@qt.io>

ASSERT failure in QList<T>::at: "index out of range" for documentation
modules that do not have any headers.

Change-Id: Ia8bc776d9c48c34b962356a65f74b2c7fe1d2d8c
Reviewed-by: Martin Smith <martin.smith@qt.io>

We pass the size_t of an std::vector to a clang function taking an
int as an argument, which on MSVC resulted in

warning C4267: 'argument': conversion from 'size_t' to 'int',
               possible loss of data

To fix this, cast explicitly.

Change-Id: I3636f7ced600c387c678aa59012274db490d8f8d
Reviewed-by: Jędrzej Nowacki <jedrzej.nowacki@qt.io>
Reviewed-by: Martin Smith <martin.smith@qt.io>

This update fixes a bug caused by reusing an index varible
name declared in an outer loop in an inner loop, which made
qdoc crash in one case.

Change-Id: I27abb4ea3241be620c8c226732e83ef42b575da9
Reviewed-by: Topi Reiniö <topi.reinio@qt.io>
Reviewed-by: Jędrzej Nowacki <jedrzej.nowacki@qt.io>

Now that clang-qdoc uses clang to parse the \fn commands,
it must handle the QPrivateSignal flag correctly. It is not
allowed in the signature in the \fn command. This update
corrects a bug where the expected number or parameters was
being reduced by 1 because the flag appeared in the declaration
in the include file.

Change-Id: I1c974100b2017b3058040937a03500a75dc69d82
Reviewed-by: Topi Reiniö <topi.reinio@qt.io>

This change replaces the last uses of qdoc's old, ad hoc
C++ parser. Clang is now used for parsing all C++ code.
\macro, \qmlxxx, and \jsxxx commands are parsed by simple
pattern matching functions using QString::split().

Change-Id: If6f95b0487d1dd3206373bc55ec8e6b8b9c55b1e
Reviewed-by: Edward Welbourne <edward.welbourne@qt.io>

qdoc now uses clang to parse \fn commands. It even handles the multiple
\fn case.

Change-Id: I259fcdfc1bf180d32ef1cc9886a48aa3006e18fb
Reviewed-by: Martin Smith <martin.smith@qt.io>

This change replaces two uses of QRegularExpression
with a simple ad hoc parser. qdoc is not allowed to
use QRegularExpression because it is not in the
bootstrap library.

Task-number: QTBUG-62845
Change-Id: Icfaca2181ff1879f02d111626a85fb3da758c731
Reviewed-by: Martin Smith <martin.smith@qt.io>

clangcodeparser.cpp:1025:39: error: no match for ‘operator+=’ (operand types are ‘QByteArray’ and ‘QChar’).

Change-Id: Ibc6fa1f11996e9ab5805b85b3165da3b1d7b2afb
Reviewed-by: Martin Smith <martin.smith@qt.io>

This change is a partial fix for the multi-\fn documentation concept.
It outputs the documentation once but listing all the function signatures
from the \fn commands found in the qdoc comment.

Multiple \since commands are not implemented; the \until command is not
implemented, and providing text applicable to a specific \fn signature is
not implemented.

This change requires clang, which means it requires a sequence of other
updates as well, so you can't test it unless you have all that stuff.

Task-number: QTBUG-60420
Change-Id: Ib316b6f97fa427ef730c4badfc785101bff55dce
Reviewed-by: Topi Reiniö <topi.reinio@qt.io>

qdoc doesn't need to see declarations of anonymous structs.
When it does see one inside a class or struct that is named,
then the html generator tries to overwrite the html file for
the outer class or struct. That causes a few qdoc error
messages and it overwrites the html file for the class
reference page and the all-members page. This update tells
clang not to visit the declaration of the anonymous struct,
so the html generator doesn't see it as something to be
documented.

Change-Id: Ie8c732e650c39f78c1374523d72a7e0448a31ba3
Reviewed-by: Topi Reiniö <topi.reinio@qt.io>

When clangqdoc encounters an unnamed enum type in a class,
qdoc reports an error that enum type "global" is not found
in any header file, and then the identifiers in the enum
type can't be properly documented. This change makes the
clang qdoc visitor name the unnamed enum type "anonymous"
and allows it to be documented like a named enum type.

Change-Id: I8b6dbc9bb78adc5f5c39a2a2d73c27ccb4543ceb
Reviewed-by: Topi Reiniö <topi.reinio@qt.io>

moduleheader is a new config variable you can add to the
qdocconf file when the name of the module header file for
your module is different from the project name. When the
name of the module header file is different from the
project name, if you don't tell qdoc what the name of the
module header file is by setting moduleheader in the
qdocconf file, then clangqdoc will not find the module
header file to build the precomiled header with, which
will result in clang not finding a lot of stuff.

Change-Id: I0da1a0b0be05cb9e6e95e0123583ddeedaf6741d
Reviewed-by: Topi Reiniö <topi.reinio@qt.io>

These messages don't come from the warning() function
in class Location, so each one must have (qdoc) added.

Change-Id: Id49b979f8b051d8f4661fb3214989c9c959121c6
Reviewed-by: Topi Reiniö <topi.reinio@qt.io>

This update makes qdoc parse and record the presence of
ref qualifiers on the end of function declarations. It
unfortunately increases the number of qdoc errors
reported in QtBase, but that is because these functions
are not documented correctly. There will be another
update to qdoc to allow documenting multiple functions
with a single comment, which is needed for documenting
these ref qualified functions but also can be useful in
other contexts.

Change-Id: If2efb1a71c683a465d66608a20e238d84ea45d9a
Reviewed-by: Topi Reiniö <topi.reinio@qt.io>

The PCH for module QtPlatformHeaders was not being built
because there are no .cpp files there, and clangqdoc was
only building the PCH when it was asked to parse the first
.cpp file. Now it builds the PCH by a direct call from the
main.cpp file, after the headers have been gathered into a
list, but before the .cpp files are parsed.

This does reduce the qdoc error count by a few, but it does
not fix the documentation for QtPlatformHeaders. From my
debugging, it appears that visiting the PCH produces no qdoc
nodes for the C++ classes and functions, etc in the PCH.

This update also improves the selection of default include
paths when inadequate include paths are provided. That is
the case for module QtPlatformHeaders, where no include
paths are provided. The algorithm for constructing a list
of reasonable guesses is modified here.

Change-Id: I0dee8dc0279894a4482df30703657558cdb098de
Reviewed-by: Topi Reiniö <topi.reinio@qt.io>

clangqdoc now handles the type alias declaraction and provides
the \typealias command for documenting it. It is documented as
a typedef.

Task-number: QTBUG-58158
Change-Id: Iee0c8dea66026a89b3625b40b92b056cada893c1
Reviewed-by: Topi Reiniö <topi.reinio@qt.io>

clangqdoc was unable to find base class nodes,
when the base class node was in a different module
from the subclass. This was mostly because the
fixInheritance() function, which handles base class
resolution after the headers have been parsed, was
being called before the headers were parsed. This
was caused by the new parsing strategy for clangqdoc,
which is to use the old loop where qdoc used to parse
the header files only to build up a list of all the
required header files and to delay parsing the header
files until clang is called to build the PCH.

The basic fix is to mode the call to resolveInheritance()
from main.cpp into clangcodeparser.cpp right after the
PCH is built. There are also a few other minor changes
in this change that make the base class resolution more
robust by ensuring that as much useful information as
possible is retained in the index file and in the base
class list for a class node.

Change-Id: I51433f618cdf40b37b0687ff1686da03359de111
Reviewed-by: Topi Reiniö <topi.reinio@qt.io>

clangqdoc was unable to tie qdoc comments to their
function declarations for nested classes, when the
function had a formal parameter of the nested class
type. The problem was that findNodeForCursor() didn't
handle the type name scoping correctly.

Change-Id: I64d81377193447b1af73ecd107f0431fac0d81a7
Reviewed-by: Topi Reiniö <topi.reinio@qt.io>

We have the class declaration for QMetaObject::Connection
in qobjectdefs.h, which is outside the declaration for
QMetaObject. clangqdoc wasn't handling this correctly. It
created the class node for Connection with the wrong parent.

This update ensures that the class node for Connection is given
the class node of QMetaObject as its parent. If the semantic and
lexical parent cursors of the current cursor are not the same,
find the Aggregate node for the semantic parent cursor and use
that node as the parent when the new class node is created.

Change-Id: I40f73dad9879e39452f83bb7c0f514a7ef319208
Reviewed-by: Topi Reiniö <topi.reinio@qt.io>

(Requires clang 4.0)

Change-Id: I50240f0e4b9f538c65dbaa0e8d08469676ac9012
Reviewed-by: Topi Reiniö <topi.reinio@qt.io>

This change enables clangqdoc to identify copy constructors,
move-copy constructors, copy-assignment operators and
move-assignment operators. Identifying these special member
functions allows clangqdoc to document them automatically
if the documentation is missing, which also means fewer qdoc
error reports.

Change-Id: Ic50822c2939f0a84e707a1b3ff946bc731a0bd85
Reviewed-by: Topi Reiniö <topi.reinio@qt.io>

This change allows qdoc to avoid printing warnings about
a qdoc comment, if the comment contains the \internal
command. In these cases, the comment will not be
used in the documentation, so there is no point reporting
warnings about it. However, if the showinternal option is
used, warnings about comments marked internal are printed
anyway.

Change-Id: Idcb329958681523c79e9f6a3a144ae26d44a6906
Reviewed-by: Topi Reiniö <topi.reinio@qt.io>

The qdoc 'defines' config variable lists values
that contain '*' to represent wildcards, but clang
doesn't accept them. This change adds a new config
variable called 'clangdefines' which explicitly
lists all the defines that match the wildcards.
It also lists several Qt defines for C++11 stuff,
because when clangqdoc comes into use, all the
supported compilers for Qt will support C++11
constructs.

There might be a few defines listed in clangdefines
that are unnecessary and maybe a few that we really
should not include, but we can adjust the list as
needed.

Also included in this change: Tell clang never to fail
(i.e. keep parsing no matter how many errors are found),
and tell clang not to print parsing errors, because they
obscure the qdoc errors in the output. clangqdoc should
assume that the source files are correct, but some of the
include files, especially system level stuff, will not be
present. clangqdoc doesn't care about these missing files,
because they aren't part of the documentation.

Change-Id: I84e1cae24d961a82d16ee705333d6f36955d35de
Reviewed-by: Topi Reiniö <topi.reinio@qt.io>

Including the module's private headers in the PCH
database can reduce the qdoc run time for the module
by a few minutes. Apparently, including the private
headers significantly reduces the number of header
files that must be re-parsed.

This change adds the module's private headers to the
pre-compiled header database. When it finds the module's
module header, it copies that module header to the
temporary directory where it will construct the PCH.
Then it finds the module's private header subdirectory,
constructs the path to each header in that directory,
and appends it to the temporary module header. Then
it passes this augmented module header to clang to
construct the PCH.

Change-Id: Ie67485c7070ef7487345db90a8b27c64f5caa0f2
Reviewed-by: Topi Reiniö <topi.reinio@qt.io>