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


  • Moderators

    @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



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


  • Qt Champions 2018

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



  • @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' ".


  • Qt Champions 2018

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



  • @jsulm
    But isn't QDoc a usable tool?Comparing the comments in Qt source code and official document,it seems QDoc is used.



  • @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.


  • Moderators

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


  • Lifetime Qt Champion



  • @raven-worx
    But all output is above.



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



  • @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:
    0_1556198443281_widgettest.png


  • Lifetime Qt Champion

    Hi
    Did you change config file to match ?
    sample uses

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


  • @mrjj
    Yes,I changed that.


  • Lifetime Qt Champion

    @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



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


  • Lifetime Qt Champion

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



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


  • Lifetime Qt Champion

    @Stephen-INF
    I might :)



  • @mrjj
    Hi, I have a very simila problem.


  • Lifetime Qt Champion

    @FrancoF
    Hi
    I did try the QDoc but could not get any /fn to work either.

    What version of Qt are you using ?



  • Re: [Why QDoc don't work](it's really confusing.)
    I have the same issue with Qt5.12.0 on Windows. Does anyone have the solution for this?
    Some notes - the enumerator was processed without problems:

    class MyClass
    {
    public:
    enum Type
    {
    }
    void foo();
    }

    /*!
    \enum MyClass::Type - parsed without errors
    \value …
    */

    /*!
    \fn void MyClass::foo() - error: use of undeclared identifier 'MyClass' why???
    */



  • To fix the error, you need to switch to VS2015 Build Tool. For VS2017 I could not get the compiler to work. But for 2015 everything works as expected.


Log in to reply
 

Looks like your connection to Qt Forum was lost, please wait while we try to reconnect.