Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Demangled name of private Python class field not correctly handled #10241

Open
lelegard opened this issue Aug 18, 2023 · 5 comments
Open

Demangled name of private Python class field not correctly handled #10241

lelegard opened this issue Aug 18, 2023 · 5 comments
Labels
enhancement a request to enhance doxygen, not a bug needinfo reported bug is incomplete, please add additional info Python

Comments

@lelegard
Copy link

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 albert-github added enhancement a request to enhance doxygen, not a bug needinfo reported bug is incomplete, please add additional info Python labels Aug 18, 2023
@albert-github
Copy link
Collaborator

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
Copy link
Author

lelegard commented Aug 18, 2023

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

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

@albert-github
Copy link
Collaborator

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
Copy link
Author

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
Copy link
Author

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...)

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
enhancement a request to enhance doxygen, not a bug needinfo reported bug is incomplete, please add additional info Python
Projects
None yet
Development

No branches or pull requests

2 participants