Uploaded image for project: 'Qt'
  1. Qt
  2. QTBUG-86665

QDoc fails to resolve function arguments with namespaces

    XMLWordPrintable

    Details

    • Type: Bug
    • Status: Closed
    • Priority: P2: Important
    • Resolution: Done
    • Affects Version/s: 5.15.0
    • Fix Version/s: None
    • Component/s: Build tools: qdoc
    • Labels:
      None
    • Commits:
      35d963c599471e7c5bb11d06850be7d05830e7cd (qt/qttools/dev)
    • Sprint:
      Da Vinci sprint 17

      Description

      Assume a type in a namespace, like "MyNamespace::Foo".

      If a function/method is declared with

      void myfun(MyNamespace::Foo foo);
      

      but the function definition leaves out the namespace via a using directive

      using MyNamespace;
      
      /*!
          The myfun function does nothing
      */
      void myfun(Foo foo) {}
      

      The qdoc fails to associate the function definition with the function declaration and claims

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

      See https://codereview.qt-project.org/c/qt-creator/qt-creator/+/311306 for a real-life example: We had perfectly working documentation for the functions in ActionManager that take a "Id" argument, as long as ActionManager and Id were in the same namespace. Now "Id" moved to the namespace "Utils", which requires us to add an error-prone \fn command to the documentation even though the function definition is still below the documentation comment.

        Attachments

        For Gerrit Dashboard: QTBUG-86665
        # Subject Branch Project Status CR V

          Activity

            People

            Assignee:
            treinio Topi Reiniƶ
            Reporter:
            con Eike Ziller
            Votes:
            0 Vote for this issue
            Watchers:
            1 Start watching this issue

              Dates

              Created:
              Updated:
              Resolved:

                Gerrit Reviews

                There are no open Gerrit changes