Demangled name of private Python class field not correctly handled

[lelegard]

This problem was briefly mentioned as part of #10231. However, #10231 was about another more general problem for which there is no consensus. This specific point is a bug.

Consider a Python class with a private field __a ("private" in the sense of #10231). According to Python rules, the actual (demangled) name of __a is _C__a, typically for disambiguated access.

## Class
class C:
    ## Constructor
    def __init__(self):
        self.__a = 'first'
        self._C__a = 'second'
    ## Method
    def test(self):
        print(self.__a)

x = C()
x.test()

The execution proves that __a and _C__a are the same:

$ python test.py 
second

However, doxygen does not recognize _C__a as the demangled form of __a:

$ ../doxygen-master/build/bin/doxygen 
test.py:6: warning: Member _C__a (variable) of class test.C is not documented.
$
$ ../doxygen-master/build/bin/doxygen --version
1.9.8 (27ba0983fdcc4b7b836e06fef90e05400d8351c8)

The variable __a is recognized as private and does not require documentation. However, _C__a is considered as an independent non-private variable and doxygen complains about the absence of documentation.

In the generated HTML, a "protected attribute" named _C__a is listed, without documentation.

Reproduction: doxybug5.zip

[albert-github]

Currently doxygen does, apparently, not know anything about this "aliasing" / "demangling" of variable names.

• are there more of these type of constructs?
• is there, authoritative, documentation about this "aliasing" / "demangling"

[lelegard]

is there, authoritative, documentation about this "aliasing" / "demangling"

From docs.python.org: https://docs.python.org/3/tutorial/classes.html#private-variables

[albert-github]

Thanks for the reference, has to be studied a bit.

One sentence that caught my eye was:

However, there is a convention that is followed by most Python code

so a nice uncertain formulation again...

[lelegard]

so a nice uncertain formulation again...

Just like almost everything in Python...

This is why the new conventions which were imposed in doxygen 1.9.6 (#10231) from a vague convention of some Python programmers, and against the traditional way of using one single underscore, can be considered as excessive.

[lelegard]

One sentence that caught my eye was:

However, there is a convention that is followed by most Python code

To be precise, this one is not about the name mangling after a double underscore, the complete sentence is:

However, there is a convention that is followed by most Python code: a name prefixed with an underscore (e.g. _spam) should be treated as a non-public part of the API

The sentence applies to identifiers with a single underscore, the old traditional convention that doxygen 1.9.6 decided to break (#10231) without notice nor option to revert to the previous behavior (OK, I admit that I am a bit insistent...)