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

Doxygen tag files have invalid data for enum types and values

    Details

    • Type: Bug
    • Status: Reported
    • Priority: P3: Somewhat important
    • Resolution: Unresolved
    • Affects Version/s: 5.9.0
    • Fix Version/s: None
    • Labels:
      None

      Description

      The generated doxygen tag files (the metadata files which enable doxygen to link e.g. from docs created for 3rd-party code into the Qt documentation for any Qt classes, types etc.) for the Qt modules have invalid data for all enum types and their values.

      Which results in instances of those enums and their values not getting backed with links into the Qt docs, lowering the quality of the docs.

      Seems the code in QDocTagFiles writing the data is incomplete/broken.

      Example Qt::Orientation

      See the type as used in the API of KSeparator not being linked here (other than the rest of Qt types/classes/typedefs/etc):
      https://api.kde.org/frameworks/kwidgetsaddons/html/classKSeparator.html

      Reason is that qtcore.tags contains this broken data:

              <member kind="enum">
                   <name>Orientation</name>
                   <anchor>Orientation-enum</anchor>
                   <arglist></arglist>
               </member>
               <member name="Horizontal">
                   <anchor>Orientation-enum</anchor>
                   <arglist></arglist>
               </member>
               <member name="Vertical">
                   <anchor>Orientation-enum</anchor>
                   <arglist></arglist>
               </member>
      

      The data should be instead like this:

               <member kind="enumeration">
                   <name>Orientation</name>
                   <anchorfile>qt.html</anchorfile>
                   <anchor>Orientation-enum</anchor>
                   <arglist></arglist>
               </member>
               <member kind="enumvalue">
                   <name>Horizontal</name>
                   <anchorfile>qt.html</anchorfile>
                   <anchor>Orientation-enum</anchor>
                   <arglist></arglist>
               </member>
               <member kind="enumvalue">
                   <name>Vertical</name>
                   <anchorfile>qt.html</anchorfile>
                   <anchor>Orientation-enum</anchor>
                   <arglist></arglist>
               </member>
      
      Code which needs fixing

      The broken code seems in QDocTagFiles::generateTagFileMembers(...), when writing the elements for Node::Enum: http://code.qt.io/cgit/qt/qttools.git/tree/src/qdoc/qdoctagfiles.cpp?h=5.9.0#n302

      I could not find a schema for the doxygen tag files, but the respective code in doxygen which reads the tag files has not seen a format-related change in years for classic enums, see TagFileParser::startMember & Co. in https://github.com/doxygen/doxygen/blob/master/src/tagreader.cpp

        Attachments

        No reviews matched the request. Check your Options in the drop-down menu of this sections header.

          Activity

            People

            • Assignee:
              gbk Martin Smith
              Reporter:
              kossebau Friedrich W. H. Kossebau
            • Votes:
              0 Vote for this issue
              Watchers:
              3 Start watching this issue

              Dates

              • Created:
                Updated:

                Gerrit Reviews

                There are no open Gerrit changes