Details
-
Bug
-
Resolution: Fixed
-
P1: Critical
-
None
-
5.14.1
-
None
-
All
-
DaVinci sprint 4
Description
In the light of trying to solve QTCREATORBUG-22451 I tried to generate documentation for a simple user project with qdoc.
See the attached example project.
It adds a class Foo with three methods, for each of these I try to get qdoc to generate documentation for me in different ways.
Run
qdoc --outputdir /tmp/testoutput qdoctest.qdocconf
in the project directory:
The result is
LOG: Start qdoc for QDocTest in dual process mode,
qdoc: warning: Dependent modules specified, but no index directories were set. There will probably be errors for missing links.
LOG: No include paths passed to qdoc; guessing reasonable include paths
LOG: Build & visit PCH for QDocTest
(qdoc) Could not find the module header in include paths for module "QDocTest" (include paths: QVector() )
Artificial module header built from header dirs in qdocconf file
LOG: clang not printing errors; include paths were guessed
LOG: PCH built & visited for QDocTest
LOG: Parse source files for QDocTest
LOG: No include paths passed to qdoc; guessing reasonable include paths
/Users/ziller/temp/qdoctest/main.cpp:37: (qdoc) warning: Cannot tie this documentation to anything
[qdoc found a /*! ... */ comment, but there was no topic command (e.g., '\fn', '\page') in the comment and no function definition following the comment.]
/Users/ziller/temp/qdoctest/main.cpp:42: (qdoc) warning: clang found diagnostics parsing \fn void Foo::bar(QVector<int> parameter)
error: variable has incomplete type 'void'
error: use of undeclared identifier 'QVector'
error: expected '(' for function-style cast or type construction
error: use of undeclared identifier 'parameter'
error: expected ';' after top level declarator
LOG: Source files parsed for QDocTest
LOG: End qdoc for QDocTest in dual process mode,
For the first function "Foo::foo" for which I don't specify a "
fn", qdoc fails to tie the documentation to anything.
For the first function "Foo::bar", for which I specify a "
fn" with parameter type "QVector<int>" it fails to find the types.
For the last function, "Foo::blah", for which I specify a type of "void Foo::blah(QVector parameter)" (though it should be "QVector<int>") qdoc does generate documentation, but instead of QVector as the parameter type, the result specifies "int" as the parameter type, probably because of the compiler defaulting all unknown types to int.
I fail to find out what the "guessed reasonable include paths" are, but it seems to not include Qt.
Second try. Run
qdoc --outputdir /tmp/testoutput qdoctest.qdocconf -I ~/Qt/5.14.1/clang_64/lib/QtCore.framework/Headers -F ~/Qt/5.14.1/clang_64/lib
(this is on macOS).
The output shows lots of errors like
/Users/ziller/QtOnline/5.14.1/clang_64/lib/QtCore.framework/Versions/5/Headers/qvector.h:43:10: fatal error: 'QtCore/qalgorithms.h' file not found .... /Users/ziller/QtOnline/5.14.1/clang_64/lib/QtCore.framework/Versions/5/Headers/qvector.h:50:10: fatal error: 'iterator' file not found ...
So it
- Fails to find standard C++ includes (iterator).
- Fails to resolve framework style includes ("QtCore/qalgorithms.h"). qdoc outputs the "include paths" it thinks it should use somewhere, which is "(include paths: QVector("-I/Users/ziller/QtOnline/5.14.1/clang_64/lib/QtCore.framework/Versions/5/Headers", "-I-F/Users/ziller/QtOnline/5.14.1/clang_64/lib"))". Note that "-I-F" which probably should just be "-F".
Attachments
Issue Links
- is required for
-
-
- Closed
-