Details
-
Bug
-
Resolution: Done
-
P3: Somewhat important
-
5.9.0, 5.14.1
-
None
-
1
-
2af1e2fe77a5a8f83d343f5d06923b070e486f41 (qt/qttools/5.15)
-
DaVinci sprint 3
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