Python private class incorrectly expects documentation for its methods

[lelegard]

Hi,

With the current state of the repo (1.9.8), when private elements are not documented, doxygen still requires documentation for the components of a Python private class.

Example test.py:

# Private class, undocumented
class __C1:
    # Method of an undocumented class, shall not be documented
    def test(self):
        # Field of an undocumented class, shall not be documented
        self.a = None

## Public class, documented
class C2:
    ## Public method of a documented class
    def test(self):
        pass

Output:

$ ../doxygen-master/build/bin/doxygen
test.py:4: warning: Member test(self) (function) of class test::__C1 is not documented.
test.py:6: warning: Member a (variable) of class test::__C1 is not documented.
$ ../doxygen-master/build/bin/doxygen --version
1.9.8 (a996a63a5a7527b29117737db60019ade81d7fa7)

Set of files to reproduce: doxybug3.zip

Doxygen does not complain that the private class __C1 is not documented. However, it complains that the method and fields of the private class are not documented.

It does not make sense to document fields of something which is not documented. When documentation is not required for private elements, the resulting documentation is for the user of the module. Everything that is not accessible to the user (such as elements of private classes) shall not need documentation either.

See #10231 for a discussion on private identifiers.

Additional minor anomaly, the class name is designated as test::__C1 in the error message. This is a C++ notation. Since the class is a Python one, it should be named as test.__C1.

[albert-github]

Regarding the minor issue with the :: versus . in the warning I've just pushed a proposed patch, pull request #10236
(Note: there might be other places as well that have not yet been identified).

[albert-github]

Regarding the main problem: I've just pushed a proposed patch, pull request #10237

[lelegard]

Thanks @albert-github

What about the status of private fields in general, as discussed in #10231? First, it breaks lots of code which use the traditional single-underscore convention for private fields. Second, using the demangled syntax to access double-underscore private fields generates an error.

[albert-github]

Code of #10236 (minor issue with the :: versus .) has been integrated in master on GitHub (please don't close the issue as this will be done at the moment of an official release).

[albert-github]

Code of #10276 (main problem) has been integrated in master on GitHub (please don't close the issue as this will be done at the moment of an official release).

[doxygen]

This issue was previously marked 'fixed but not released',
which means it should be fixed in doxygen version 1.9.8.
Please verify if this is indeed the case. Reopen the
issue if you think it is not fixed and please include any additional information
that you think can be relevant (preferably in the form of a self-contained example).

[doxygen]

This issue was previously marked 'fixed but not released',
which means it should be fixed in doxygen version 1.9.8.
Please verify if this is indeed the case. Reopen the
issue if you think it is not fixed and please include any additional information
that you think can be relevant (preferably in the form of a self-contained example).