Why QDoc don't work, it's really confusing.
-
Hi,I want to generate documentation with qdoc,and I tried as the qdoc guide told，I can get documentation,but it's not full,I don't know why,can anyone help?thanks.
I tried both on:
qt 5.11.3
llvm 6.0.1
windows 10and:
qt 5.12.3
llvm 6.0.1
ubuntu 16.04but it's all the same.
here is the code:
project.qconconf
headerdirs = . sourcedirs = . exampledirs = . imagedirs = ./images sources.fileextensions = "*.cpp *.qdoc *.mm *.qml" headers.fileextensions = "*.h *.ch *.h++ *.hh *.hpp *.hxx" examples.fileextensions = "*.cpp *.h *.js *.xq *.svg *.xml *.ui *.qhp *.qhcp *.qml" examples.imageextensions = "*.png *.jpeg *.jpg *.gif *.mng" outputdir = html outputformats = HTMLmainwindow.cpp
/*! * \class MainWindow * \brief mainwindow for ui . */ /*! constructor */ MainWindow::MainWindow(QWidget *parent) : QMainWindow(parent), ui(new Ui::MainWindow) { ui->setupUi(this); } /*! destructor */ MainWindow::~MainWindow() { delete ui; } /*! function test */ bool MainWindow::test() const { return test_; } /*! function setTest */ void MainWindow::setTest(bool test) { test_ = test; }After I execute command "qdoc proect.qdocconf",warning as follows:
.../mainwindow.cpp:4: (qdoc) warning: Class MainWindow has no \inmodule command; using project name by default:
.../mainwindow.cpp:9: (qdoc) warning: Cannot tie this documentation to anything
[I found a /*! ... */ comment, but there was no topic command (e.g., '\fn', '\page') in the comment and no function definition following the comment.]what I got:
two file: ".index" and "mainwindow.html""mainwindow.html":
MainWindow
Contents
Detailed Description
MainWindow Class
mainwindow for ui interface. More...Detailed Description
mainwindow for ui interface.Seems like it can't get any other info except "\class".
Any suggestion would be appreciated.
@Stephen-INF said in Why QDoc don't work ,It's really confusing.:
I can get documentation,but it's not full
you do not document any proeprties, methods, signals, etc.
/*! function test */This is not a valid qdoc command. You should use
\fnfor example here.
https://doc.qt.io/qt-5/13-qdoc-commands-topics.html -
@Stephen-INF said in Why QDoc don't work ,It's really confusing.:
I can get documentation,but it's not full
you do not document any proeprties, methods, signals, etc.
/*! function test */This is not a valid qdoc command. You should use
\fnfor example here.
https://doc.qt.io/qt-5/13-qdoc-commands-topics.htmlwrote on 25 Apr 2019, 02:31 last edited by@raven-worx
Thank you,but I have tried this and received warning:warning: clang found diagnostics parsing \fn MainWindow::MainWindow(QWidget *parent) error: use of undeclared identifier 'MainWindow' error: unknown type name 'QWidget'Besides,in here https://doc.qt.io/qt-5/qtwritingstyle-cpp.html,I saw
"Typically, function documentation immediately precedes the implementation of the function in the .cpp file. For function documentation that is not immediately above the implementation, the \fn is needed."
And I also referenced the comment format of Qt source code,there is no "\fn" topic command,if the comment is above the function implementation.
Still don't know how to do this,is there any details I miss？ -
@raven-worx
Thank you,but I have tried this and received warning:warning: clang found diagnostics parsing \fn MainWindow::MainWindow(QWidget *parent) error: use of undeclared identifier 'MainWindow' error: unknown type name 'QWidget'Besides,in here https://doc.qt.io/qt-5/qtwritingstyle-cpp.html,I saw
"Typically, function documentation immediately precedes the implementation of the function in the .cpp file. For function documentation that is not immediately above the implementation, the \fn is needed."
And I also referenced the comment format of Qt source code,there is no "\fn" topic command,if the comment is above the function implementation.
Still don't know how to do this,is there any details I miss？@Stephen-INF said in Why QDoc don't work, it's really confusing.:
warning: clang found diagnostics parsing \fn MainWindow::MainWindow(QWidget *parent)
error: use of undeclared identifier 'MainWindow'
error: unknown type name 'QWidget'Can you show how you use \fn? It should be part of the doc comment.
-
@Stephen-INF said in Why QDoc don't work, it's really confusing.:
warning: clang found diagnostics parsing \fn MainWindow::MainWindow(QWidget *parent)
error: use of undeclared identifier 'MainWindow'
error: unknown type name 'QWidget'Can you show how you use \fn? It should be part of the doc comment.
wrote on 25 Apr 2019, 09:37 last edited by@jsulm
Thank you for you help,here is my test code/*! \fn MainWindow::MainWindow(QWidget *parent) Constructor Mainwindow */ MainWindow::MainWindow(QWidget *parent) : QMainWindow(parent), ui(new Ui::MainWindow) { ui->setupUi(this); }But I think the issue might be related to "error: use of undeclared identifier 'MainWindow' ".
-
@jsulm
Thank you for you help,here is my test code/*! \fn MainWindow::MainWindow(QWidget *parent) Constructor Mainwindow */ MainWindow::MainWindow(QWidget *parent) : QMainWindow(parent), ui(new Ui::MainWindow) { ui->setupUi(this); }But I think the issue might be related to "error: use of undeclared identifier 'MainWindow' ".
@Stephen-INF This error comes from CLang code model. I guess it does not understand this QDoc syntax.
-
@Stephen-INF This error comes from CLang code model. I guess it does not understand this QDoc syntax.
wrote on 25 Apr 2019, 11:49 last edited by@jsulm
But isn't QDoc a usable tool?Comparing the comments in Qt source code and official document,it seems QDoc is used. -
@Stephen-INF said in Why QDoc don't work ,It's really confusing.:
I can get documentation,but it's not full
you do not document any proeprties, methods, signals, etc.
/*! function test */This is not a valid qdoc command. You should use
\fnfor example here.
https://doc.qt.io/qt-5/13-qdoc-commands-topics.htmlwrote on 25 Apr 2019, 12:00 last edited by@raven-worx
Hi，I really want to try Qdoc,and I have spent many hours，still don't know where I am doing wrong.If QDoc is usable for you，can you give me an example,thanks a lot. -
@raven-worx
Hi，I really want to try Qdoc,and I have spent many hours，still don't know where I am doing wrong.If QDoc is usable for you，can you give me an example,thanks a lot.@Stephen-INF
in the end we are talking about a CLANG warning. This shouldn't influence QDoc though.
QDoc should output something meaningful in the meantime or? -
Hi
Maybe try a simple sample and see ?
https://retifrav.github.io/blog/2017/05/24/documenting-qt-project-with-qdoc/ -
@Stephen-INF
in the end we are talking about a CLANG warning. This shouldn't influence QDoc though.
QDoc should output something meaningful in the meantime or?wrote on 25 Apr 2019, 12:18 last edited by@raven-worx
But all output is above. -
Hi
Maybe try a simple sample and see ?
https://retifrav.github.io/blog/2017/05/24/documenting-qt-project-with-qdoc/wrote on 25 Apr 2019, 12:28 last edited by@mrjj
Thanks a lot,I will try it now.(Sorry for reply late...) -
Hi
Maybe try a simple sample and see ?
https://retifrav.github.io/blog/2017/05/24/documenting-qt-project-with-qdoc/wrote on 25 Apr 2019, 13:21 last edited by@mrjj
I tried,QDoc works well with qml ,but C++ Class still do not works.
I found generate documentation for qml only need one "source" file,but C++ class need both "source" and "header" file.
I guess there might be something wrong with header file ?So QDoc can't analyse source file as normal.New C++ class "WidgetTest" added in project privided in the link.
header file:
#include <QWidget> class WidgetTest : public QWidget { Q_OBJECT public: explicit WidgetTest(QWidget *parent = nullptr); };source file without "\fn":
/*! \class WidgetTest \brief WidgetTest for ui interface. \inmodule module0 */ /*! WidgetTest::WidgetTest(QWidget *parent) constructor WidgetTest */ WidgetTest::WidgetTest(QWidget *parent) : QWidget(parent) { }output:
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.]source file with "\fn":
/*! \class WidgetTest \brief WidgetTest for ui interface. \inmodule module0 */ /*! \fn WidgetTest::WidgetTest(QWidget *parent) constructor WidgetTest */ WidgetTest::WidgetTest(QWidget *parent) : QWidget(parent) { }output:
warning: clang found diagnostics parsing \fn WidgetTest::WidgetTest(QWidget *parent) error: use of undeclared identifier 'WidgetTest' error: unknown type name 'QWidget'widgettest.html is same:
-
Hi
Did you change config file to match ?
sample usesheaders.fileextensions = "*.hpp" but often its actually just "*.h" -
Hi
Did you change config file to match ?
sample usesheaders.fileextensions = "*.hpp" but often its actually just "*.h" -
@mrjj
Yes，I changed that.@Stephen-INF
hmm odd. then
it seems clang have issue parsing the header
( QDoc uses clang from Qt 5.11)You did follow step to install it ?
https://doc.qt.io/qt-5/qdoc-guide-clang.html -
@Stephen-INF
hmm odd. then
it seems clang have issue parsing the header
( QDoc uses clang from Qt 5.11)You did follow step to install it ?
https://doc.qt.io/qt-5/qdoc-guide-clang.htmlwrote on 25 Apr 2019, 14:01 last edited by@mrjj
Yes，I did it
installed LLVM6.0.1 and specify Clang location by "set LLVM_INSTALL_DIR=C:\Program Files\LLVM" -
@mrjj
Yes，I did it
installed LLVM6.0.1 and specify Clang location by "set LLVM_INSTALL_DIR=C:\Program Files\LLVM"@Stephen-INF
That seems pretty ok.
However, since the other part of generation seems to work, then
it must be something with clang and /fn
But I cant guess what not right. -
@Stephen-INF
That seems pretty ok.
However, since the other part of generation seems to work, then
it must be something with clang and /fn
But I cant guess what not right.wrote on 25 Apr 2019, 14:51 last edited by@mrjj
Well,can you try to generate C++ documentation with QDoc if you are free? -
@mrjj
Well,can you try to generate C++ documentation with QDoc if you are free?@Stephen-INF
I might :)
