Skip to content
  • Categories
  • Recent
  • Tags
  • Popular
  • Users
  • Groups
  • Search
  • Get Qt Extensions
  • Unsolved
Collapse
Brand Logo
  1. Home
  2. Qt Development
  3. General and Desktop
  4. Why QDoc don't work, it's really confusing.
Forum Update on Monday, May 27th 2025

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

Scheduled Pinned Locked Moved Unsolved General and Desktop
qdoc
26 Posts 7 Posters 6.2k Views
  • Oldest to Newest
  • Newest to Oldest
  • Most Votes
Reply
  • Reply as topic
Log in to reply
This topic has been deleted. Only users with topic management privileges can see it.
  • Stephen INFS 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?

    jsulmJ Offline
    jsulmJ Offline
    jsulm
    Lifetime Qt Champion
    wrote on last edited by
    #4

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

    https://forum.qt.io/topic/113070/qt-code-of-conduct

    Stephen INFS 1 Reply Last reply
    0
    • jsulmJ 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 INFS Offline
      Stephen INFS Offline
      Stephen INF
      wrote on last edited by
      #5

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

      jsulmJ 1 Reply Last reply
      0
      • Stephen INFS 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' ".

        jsulmJ Offline
        jsulmJ Offline
        jsulm
        Lifetime Qt Champion
        wrote on last edited by
        #6

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

        https://forum.qt.io/topic/113070/qt-code-of-conduct

        Stephen INFS 1 Reply Last reply
        0
        • jsulmJ jsulm

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

          Stephen INFS Offline
          Stephen INFS Offline
          Stephen INF
          wrote on last edited by
          #7

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

          1 Reply Last reply
          0
          • raven-worxR 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 INFS Offline
            Stephen INFS Offline
            Stephen INF
            wrote on last edited by
            #8

            @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-worxR 1 Reply Last reply
            0
            • Stephen INFS 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-worxR Offline
              raven-worxR Offline
              raven-worx
              Moderators
              wrote on last edited by
              #9

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

              --- SUPPORT REQUESTS VIA CHAT WILL BE IGNORED ---
              If you have a question please use the forum so others can benefit from the solution in the future

              Stephen INFS 1 Reply Last reply
              2
              • mrjjM Offline
                mrjjM Offline
                mrjj
                Lifetime Qt Champion
                wrote on last edited by
                #10

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

                Stephen INFS 2 Replies Last reply
                1
                • raven-worxR 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?

                  Stephen INFS Offline
                  Stephen INFS Offline
                  Stephen INF
                  wrote on last edited by
                  #11

                  @raven-worx
                  But all output is above.

                  1 Reply Last reply
                  0
                  • mrjjM mrjj

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

                    Stephen INFS Offline
                    Stephen INFS Offline
                    Stephen INF
                    wrote on last edited by
                    #12

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

                    1 Reply Last reply
                    0
                    • mrjjM mrjj

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

                      Stephen INFS Offline
                      Stephen INFS Offline
                      Stephen INF
                      wrote on last edited by
                      #13

                      @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

                      1 Reply Last reply
                      0
                      • mrjjM Offline
                        mrjjM Offline
                        mrjj
                        Lifetime Qt Champion
                        wrote on last edited by mrjj
                        #14

                        Hi
                        Did you change config file to match ?
                        sample uses

                        headers.fileextensions = "*.hpp"
                        but often its actually just "*.h"
                        
                        Stephen INFS 1 Reply Last reply
                        0
                        • mrjjM mrjj

                          Hi
                          Did you change config file to match ?
                          sample uses

                          headers.fileextensions = "*.hpp"
                          but often its actually just "*.h"
                          
                          Stephen INFS Offline
                          Stephen INFS Offline
                          Stephen INF
                          wrote on last edited by
                          #15

                          @mrjj
                          Yes,I changed that.

                          mrjjM 1 Reply Last reply
                          0
                          • Stephen INFS Stephen INF

                            @mrjj
                            Yes,I changed that.

                            mrjjM Offline
                            mrjjM Offline
                            mrjj
                            Lifetime Qt Champion
                            wrote on last edited by
                            #16

                            @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 INFS 1 Reply Last reply
                            1
                            • mrjjM 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 INFS Offline
                              Stephen INFS Offline
                              Stephen INF
                              wrote on last edited by
                              #17

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

                              mrjjM 1 Reply Last reply
                              0
                              • Stephen INFS Stephen INF

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

                                mrjjM Offline
                                mrjjM Offline
                                mrjj
                                Lifetime Qt Champion
                                wrote on last edited by
                                #18

                                @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 INFS 1 Reply Last reply
                                0
                                • mrjjM 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 INFS Offline
                                  Stephen INFS Offline
                                  Stephen INF
                                  wrote on last edited by
                                  #19

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

                                  mrjjM 1 Reply Last reply
                                  0
                                  • Stephen INFS Stephen INF

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

                                    mrjjM Offline
                                    mrjjM Offline
                                    mrjj
                                    Lifetime Qt Champion
                                    wrote on last edited by
                                    #20

                                    @Stephen-INF
                                    I might :)

                                    1 Reply Last reply
                                    0
                                    • F Offline
                                      F Offline
                                      FrancoF
                                      wrote on last edited by
                                      #21

                                      @mrjj
                                      Hi, I have a very simila problem.

                                      mrjjM 1 Reply Last reply
                                      0
                                      • F FrancoF

                                        @mrjj
                                        Hi, I have a very simila problem.

                                        mrjjM Offline
                                        mrjjM Offline
                                        mrjj
                                        Lifetime Qt Champion
                                        wrote on last edited by
                                        #22

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

                                        What version of Qt are you using ?

                                        DevMachinesD F 2 Replies Last reply
                                        0
                                        • mrjjM mrjj

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

                                          What version of Qt are you using ?

                                          DevMachinesD Offline
                                          DevMachinesD Offline
                                          DevMachines
                                          wrote on last edited by DevMachines
                                          #23

                                          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???
                                          */

                                          1 Reply Last reply
                                          0

                                          • Login

                                          • Login or register to search.
                                          • First post
                                            Last post
                                          0
                                          • Categories
                                          • Recent
                                          • Tags
                                          • Popular
                                          • Users
                                          • Groups
                                          • Search
                                          • Get Qt Extensions
                                          • Unsolved