Why QDoc don't work, it's really confusing.

[Stephen INF]

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 10

and:
qt 5.12.3
llvm 6.0.1
ubuntu 16.04

but 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 = HTML

mainwindow.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.

[raven-worx]

@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 \fn for example here.
https://doc.qt.io/qt-5/13-qdoc-commands-topics.html

[Stephen INF]

@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？

[jsulm]

@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]

@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]

@Stephen-INF This error comes from CLang code model. I guess it does not understand this QDoc syntax.

[Stephen INF]

@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]

@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]

@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?

[mrjj]

Hi
Maybe try a simple sample and see ?
https://retifrav.github.io/blog/2017/05/24/documenting-qt-project-with-qdoc/

[Stephen INF]

@raven-worx
But all output is above.

[Stephen INF]

@mrjj
Thanks a lot,I will try it now.(Sorry for reply late...)

[Stephen INF]

@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:

[mrjj]

Hi
Did you change config file to match ?
sample uses

headers.fileextensions = "*.hpp"
but often its actually just "*.h"

[Stephen INF]

@mrjj
Yes，I changed that.

[mrjj]

@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]

@mrjj
Yes，I did it
installed LLVM6.0.1 and specify Clang location by "set LLVM_INSTALL_DIR=C:\Program Files\LLVM"

[mrjj]

@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]

@mrjj
Well,can you try to generate C++ documentation with QDoc if you are free?

[mrjj]

@Stephen-INF
I might :)