search

doxygen / doxygen

Official doxygen git repository
https://www.doxygen.org
GNU General Public License v2.0
5.59k stars 1.27k forks source link

Doxygen version 1.12.0 failing to differentiate certain overloads when using `qtbluetooth.tags` tag file #11065

Open pcolby opened 1 month ago

pcolby commented 1 month ago

Doxygen v1.12.0 fails to distinguish overloads of a very specific type when using tag files, where previous versions would correctly differentiate.

To Reproduce

Consider the following files (sources also attached in tarball at the end):

scancommand.h

class ScanCommand
{
    void toJson(const QBluetoothDeviceInfo::CoreConfigurations &configurations);
    void toJson(const QBluetoothDeviceInfo::ServiceClasses &classes);
};

scancommand.cpp

#include "scancommand.h"

#include <QBluetoothDeviceInfo>

/*!
 * \class ScanCommand
 *
 * The ScanCommand class implements ...
 */

/*!
 * Overload that takes an `QBluetoothDeviceInfo::CoreConfigurations` arg.
 */
void ScanCommand::toJson(const QBluetoothDeviceInfo::CoreConfigurations &configurations)
{
}

/*!
 * Overload that takes a `QBluetoothDeviceInfo::ServiceClasses` arg.
 */
void ScanCommand::toJson(const QBluetoothDeviceInfo::ServiceClasses &classes)
{
}

Doxyfile

EXTRACT_PRIVATE        = YES
QUIET                  = YES
INPUT                  = src
TAGFILES               = "/path/to/qtbluetooth.tags=https://doc.qt.io/qt-6/"

With Doxygen version 1.9.8, 1.10.0 and 1.11.0 (only ones I've tested), this would work as expected (finding two functions, and allocating their docs accordingly), like this:

image

However, with Doxygen version 1.12.0, I get:

scancommand.h:4: warning: Member toJson(const QBluetoothDeviceInfo::ServiceClasses &classes) (function) of class ScanCommand is not documented.

And in the resulting HTML output, the documentation markup for both functions appears (combined) against the first overload only, like this:

image

Additional Context

Tested on Ubuntu 23.10 and 24.04.

This does seems to be specific to using external tag files. I'm not sure if the bug is specific to qtbluetooth.tags or if any other tags files will have the same issue. Note the tag files (also included in the tarball) are the official ones installed via Qt's online installer.

As I happen to have a few Doxygen versions installed, as well as a few Qt versions, I've constructed a quick script (also included in the tarball) to run all combinations I have readily available:

#!/usr/bin/env bash

set -o errexit -o noclobber -o nounset -o pipefail

: "${DOX_PATH:=$HOME/opt}"

for doxVer in 1.9.8 1.10.0 1.11.0 1.12.0; do
  for qtVer in 5.9.9 5.11.3 5.12.12 5.13.2 5.14.2 5.15.2 6.2.4 6.3.2 6.4.3 6.5.3 6.6.3 6.7.2 6.8.0; do
    export DOX_VER="$doxVer" QT_VER="$qtVer"
    envsubst < Doxyfile.in >| "Doxyfile-$doxVer-$qtVer"
    echo "doxygen version: $("$DOX_PATH/doxygen-$doxVer/bin/doxygen" --version) Qt version: $qtVer"
    "$DOX_PATH/doxygen-$doxVer/bin/doxygen" "Doxyfile-$doxVer-$qtVer"
  done
done

When I run, I get the output:

doxygen version: 1.9.8 (c2fe5c3e4986974eb2a97608b24086683502f07f) Qt version: 5.9.9
doxygen version: 1.9.8 (c2fe5c3e4986974eb2a97608b24086683502f07f) Qt version: 5.11.3
doxygen version: 1.9.8 (c2fe5c3e4986974eb2a97608b24086683502f07f) Qt version: 5.12.12
doxygen version: 1.9.8 (c2fe5c3e4986974eb2a97608b24086683502f07f) Qt version: 5.13.2
doxygen version: 1.9.8 (c2fe5c3e4986974eb2a97608b24086683502f07f) Qt version: 5.14.2
doxygen version: 1.9.8 (c2fe5c3e4986974eb2a97608b24086683502f07f) Qt version: 5.15.2
doxygen version: 1.9.8 (c2fe5c3e4986974eb2a97608b24086683502f07f) Qt version: 6.2.4
doxygen version: 1.9.8 (c2fe5c3e4986974eb2a97608b24086683502f07f) Qt version: 6.3.2
doxygen version: 1.9.8 (c2fe5c3e4986974eb2a97608b24086683502f07f) Qt version: 6.4.3
doxygen version: 1.9.8 (c2fe5c3e4986974eb2a97608b24086683502f07f) Qt version: 6.5.3
doxygen version: 1.9.8 (c2fe5c3e4986974eb2a97608b24086683502f07f) Qt version: 6.6.3
doxygen version: 1.9.8 (c2fe5c3e4986974eb2a97608b24086683502f07f) Qt version: 6.7.2
doxygen version: 1.9.8 (c2fe5c3e4986974eb2a97608b24086683502f07f) Qt version: 6.8.0
doxygen version: 1.10.0 (ebc57c6dd303a980bd19dd74b8b61c8f3f5180ca) Qt version: 5.9.9
doxygen version: 1.10.0 (ebc57c6dd303a980bd19dd74b8b61c8f3f5180ca) Qt version: 5.11.3
doxygen version: 1.10.0 (ebc57c6dd303a980bd19dd74b8b61c8f3f5180ca) Qt version: 5.12.12
doxygen version: 1.10.0 (ebc57c6dd303a980bd19dd74b8b61c8f3f5180ca) Qt version: 5.13.2
doxygen version: 1.10.0 (ebc57c6dd303a980bd19dd74b8b61c8f3f5180ca) Qt version: 5.14.2
doxygen version: 1.10.0 (ebc57c6dd303a980bd19dd74b8b61c8f3f5180ca) Qt version: 5.15.2
doxygen version: 1.10.0 (ebc57c6dd303a980bd19dd74b8b61c8f3f5180ca) Qt version: 6.2.4
doxygen version: 1.10.0 (ebc57c6dd303a980bd19dd74b8b61c8f3f5180ca) Qt version: 6.3.2
doxygen version: 1.10.0 (ebc57c6dd303a980bd19dd74b8b61c8f3f5180ca) Qt version: 6.4.3
doxygen version: 1.10.0 (ebc57c6dd303a980bd19dd74b8b61c8f3f5180ca) Qt version: 6.5.3
doxygen version: 1.10.0 (ebc57c6dd303a980bd19dd74b8b61c8f3f5180ca) Qt version: 6.6.3
doxygen version: 1.10.0 (ebc57c6dd303a980bd19dd74b8b61c8f3f5180ca) Qt version: 6.7.2
doxygen version: 1.10.0 (ebc57c6dd303a980bd19dd74b8b61c8f3f5180ca) Qt version: 6.8.0
doxygen version: 1.11.0 (9b424b03c9833626cd435af22a444888fbbb192d) Qt version: 5.9.9
doxygen version: 1.11.0 (9b424b03c9833626cd435af22a444888fbbb192d) Qt version: 5.11.3
doxygen version: 1.11.0 (9b424b03c9833626cd435af22a444888fbbb192d) Qt version: 5.12.12
doxygen version: 1.11.0 (9b424b03c9833626cd435af22a444888fbbb192d) Qt version: 5.13.2
doxygen version: 1.11.0 (9b424b03c9833626cd435af22a444888fbbb192d) Qt version: 5.14.2
doxygen version: 1.11.0 (9b424b03c9833626cd435af22a444888fbbb192d) Qt version: 5.15.2
doxygen version: 1.11.0 (9b424b03c9833626cd435af22a444888fbbb192d) Qt version: 6.2.4
doxygen version: 1.11.0 (9b424b03c9833626cd435af22a444888fbbb192d) Qt version: 6.3.2
doxygen version: 1.11.0 (9b424b03c9833626cd435af22a444888fbbb192d) Qt version: 6.4.3
doxygen version: 1.11.0 (9b424b03c9833626cd435af22a444888fbbb192d) Qt version: 6.5.3
doxygen version: 1.11.0 (9b424b03c9833626cd435af22a444888fbbb192d) Qt version: 6.6.3
doxygen version: 1.11.0 (9b424b03c9833626cd435af22a444888fbbb192d) Qt version: 6.7.2
doxygen version: 1.11.0 (9b424b03c9833626cd435af22a444888fbbb192d) Qt version: 6.8.0
doxygen version: 1.12.0 (c73f5d30f9e8b1df5ba15a1d064ff2067cbb8267) Qt version: 5.9.9
/home/paul/src/dokit-dox/src/scancommand.h:4: warning: Member toJson(const QBluetoothDeviceInfo::ServiceClasses &classes) (function) of class ScanCommand is not documented.
doxygen version: 1.12.0 (c73f5d30f9e8b1df5ba15a1d064ff2067cbb8267) Qt version: 5.11.3
/home/paul/src/dokit-dox/src/scancommand.h:4: warning: Member toJson(const QBluetoothDeviceInfo::ServiceClasses &classes) (function) of class ScanCommand is not documented.
doxygen version: 1.12.0 (c73f5d30f9e8b1df5ba15a1d064ff2067cbb8267) Qt version: 5.12.12
/home/paul/src/dokit-dox/src/scancommand.h:4: warning: Member toJson(const QBluetoothDeviceInfo::ServiceClasses &classes) (function) of class ScanCommand is not documented.
doxygen version: 1.12.0 (c73f5d30f9e8b1df5ba15a1d064ff2067cbb8267) Qt version: 5.13.2
/home/paul/src/dokit-dox/src/scancommand.h:4: warning: Member toJson(const QBluetoothDeviceInfo::ServiceClasses &classes) (function) of class ScanCommand is not documented.
doxygen version: 1.12.0 (c73f5d30f9e8b1df5ba15a1d064ff2067cbb8267) Qt version: 5.14.2
/home/paul/src/dokit-dox/src/scancommand.h:4: warning: Member toJson(const QBluetoothDeviceInfo::ServiceClasses &classes) (function) of class ScanCommand is not documented.
doxygen version: 1.12.0 (c73f5d30f9e8b1df5ba15a1d064ff2067cbb8267) Qt version: 5.15.2
/home/paul/src/dokit-dox/src/scancommand.h:4: warning: Member toJson(const QBluetoothDeviceInfo::ServiceClasses &classes) (function) of class ScanCommand is not documented.
doxygen version: 1.12.0 (c73f5d30f9e8b1df5ba15a1d064ff2067cbb8267) Qt version: 6.2.4
/home/paul/src/dokit-dox/src/scancommand.h:4: warning: Member toJson(const QBluetoothDeviceInfo::ServiceClasses &classes) (function) of class ScanCommand is not documented.
doxygen version: 1.12.0 (c73f5d30f9e8b1df5ba15a1d064ff2067cbb8267) Qt version: 6.3.2
/home/paul/src/dokit-dox/src/scancommand.h:4: warning: Member toJson(const QBluetoothDeviceInfo::ServiceClasses &classes) (function) of class ScanCommand is not documented.
doxygen version: 1.12.0 (c73f5d30f9e8b1df5ba15a1d064ff2067cbb8267) Qt version: 6.4.3
/home/paul/src/dokit-dox/src/scancommand.h:4: warning: Member toJson(const QBluetoothDeviceInfo::ServiceClasses &classes) (function) of class ScanCommand is not documented.
doxygen version: 1.12.0 (c73f5d30f9e8b1df5ba15a1d064ff2067cbb8267) Qt version: 6.5.3
/home/paul/src/dokit-dox/src/scancommand.h:4: warning: Member toJson(const QBluetoothDeviceInfo::ServiceClasses &classes) (function) of class ScanCommand is not documented.
doxygen version: 1.12.0 (c73f5d30f9e8b1df5ba15a1d064ff2067cbb8267) Qt version: 6.6.3
/home/paul/src/dokit-dox/src/scancommand.h:4: warning: Member toJson(const QBluetoothDeviceInfo::ServiceClasses &classes) (function) of class ScanCommand is not documented.
doxygen version: 1.12.0 (c73f5d30f9e8b1df5ba15a1d064ff2067cbb8267) Qt version: 6.7.2
/home/paul/src/dokit-dox/src/scancommand.h:4: warning: Member toJson(const QBluetoothDeviceInfo::ServiceClasses &classes) (function) of class ScanCommand is not documented.
doxygen version: 1.12.0 (c73f5d30f9e8b1df5ba15a1d064ff2067cbb8267) Qt version: 6.8.0
/home/paul/src/dokit-dox/src/scancommand.h:4: warning: Member toJson(const QBluetoothDeviceInfo::ServiceClasses &classes) (function) of class ScanCommand is not documented.

So as you can see:

Please let me know if there's anything else you'd like me to check, or any other info I can provide to help. Thanks!

Attachments

albert-github commented 1 month ago

Looks like the commit:

Commit: c6b3dae2b2224bdd310350a25ed46be288679100 [c6b3dae]
Date: Friday, August 2, 2024 4:50:20 PM
Refactoring: reduce lock contention when adding cross references

is still OK but that:

Commit: 70aff92f9ecdfced4ea745c94eb98d22a90543bd [70aff92]
Date: Friday, August 2, 2024 9:04:33 PM
Fix warning: 'no uniquely matching class member found for typedef'

Regression for issue #11010 (a7179f016c974c38b3d1725dcfcb77924da8b182)

is not OK.

(I doubt that the commit

Commit: 5e70fb62419ddb06d711abf3c39e00ba220bb2a5 [5e70fb6]
Date: Friday, August 2, 2024 8:54:16 PM
Fix for failing regression test

is causing the problems)

albert-github commented 1 month ago

Looks like that a small tag file with some typedefs in it is already sufficient

Tag file; Qt-6.8.0-qtbluetooth.tags.tar.gz

doxygen commented 1 month ago

Looks like the problem is that these tag files have no type information (i.e. no <type>..</type> line) for typedefs. Since doxygen now resolves the typedefs, it resolves each of the parameter types of the overloaded toJson methods to the same (empty) string, thus matching the definitions of both overloads to the first declaration and finding no match for the second which then is reported as undocumented.

I need to find a way to prevent resolving a typedef to an empty string in such cases.

doxygen commented 1 month ago

@pcolby Please verify if the referenced commit fixes the problem for you. Do not close the issue, this will be done automatically when the next official release becomes available.

pcolby commented 1 month ago

I can confirm that the current HEAD commit has resolved the issue for me, both in my cut-down test sample, and the full project from which it came 😊 Thanks!

Tested version: 1.13.0 (c692605decbd3f78054dfc780da6749235883cb6*)