Python variables erratic documentation

[TommyPec]

Describe the bug
Sometimes the variables of a class are documented twice (one is bogus)

Screenshots

The 2nd custom_value in the screenshot is generated by this python code:

    def do_set_property(self, pspec, value):
        """!
        Set Property
        @param self this object
        @param pspec property name
        @param value property value
        @return exception if unknown property
        """
        if pspec.name == "width":
            self.custom_width = value
            self._size_changed()

            # make sure we update the display
            self.changed(True)

        elif pspec.name == "height":
            self.custom_height = value
            self._size_changed()

            # make sure we update the display
            self.changed(True)

Funny thing: the "width" part doesn't cause issues.

If I activate the warnings, I also get warnings, e.g.,

/Users/pecos/Development/workspace/ns-3-dev/src/visualizer/visualizer/svgitem.py:119: warning: Member custom_width (variable) of class visualizer.svgitem.SvgItem is not documented.

To Reproduce
example.tgz

Expected behavior
Correct documentation and no warning :)

Version
doxygen --version
1.12.0

macOS, using homebrew

[TommyPec]

A note: sometimes I'm able to silence the problem by refactoring the code, e.g., this did fix a similar issue:

-            for c in self.packet_filter_list:
-                c.selected = True
+            # ugly, but the better version generates Doxygen warnings.
+            for index in range(len(self.packet_filter_list)):
+                self.packet_filter_list[index].selected = True

[TommyPec]

Last note (I know it's external code...) but my efforts to use workarounds are here:
https://gitlab.com/nsnam/ns-3-dev/-/merge_requests/2141/

The problem is that in some cases there are no possible workarounds (and where the workaround exists, the code is ugly).

Note regression-wise, Doxygen 1.9.6 did not seem to have this issue.

[albert-github]

I don't think even doxygen 1.11.0 had the problem and that it is introduced in doxygen 1.12.0, most likely by means of #10988 where the initial values are introduced for the class (self ) variables.

[TommyPec]

I don't think even doxygen 1.11.0 had the problem and that it is introduced in doxygen 1.12.0, most likely by means of #10988 where the initial values are introduced for the class (self ) variables.

Yep, I can confirm that 1.11.0 doesn't have this issue. I'll use 1.11.0 as a temporary workaround.

[TommyPec]

Our temporary workaround ended up to be extremely temporary... archlinux did update some libraries and now there's a dependencies nightmare :(

[doxygen]

@TommyPec 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.

[TommyPec]

@albert-github tested with 1.13.0 (d3a4946*) - it looks like the bug is still there.

[TommyPec]

A further info. I checked one of the "offending" python classes, the code is:

class Node(PyVizObject):
    ## @var visualizer
    #  visualier object
    ## @var node_index
    #  node index
    ## @var canvas_item
    #  canvas item
    ## @var links
    #  links
    ## @var _has_mobility
    #  has mobility model
    ## @var _selected
    #  is selected
    ## @var _highlighted
    #  is highlighted
    ## @var _color
    #  color
    ## @var _size
    #  size
    ## @var menu
    #  menu
    ## @var svg_item
    #  svg item
    ## @var svg_align_x
    #  svg align X
    ## @var svg_align_y
    #  svg align Y
    ## @var _label
    #  label
    ## @var _label_canvas_item
    #  label canvas
    ## @var highlighted
    #  highlighted property
    ## @var selected
    #  selected property
    ## @var on_enter_notify_event
    #  on_enter_notify_event function
    ## @var on_leave_notify_event
    #  on_leave_notify_event function

    ## signal emitted whenever a tooltip is about to be shown for the node
    ## the first signal parameter is a python list of strings, to which
    ## information can be appended
    __gsignals__ = {
        "query-extra-tooltip-info": (GObject.SignalFlags.RUN_LAST, None, (object,)),
    }

The result (don't ask me why) is:

• Some of the variables are marked as not documented (e.g., warning: Member _selected (variable) of class visualizer.core.Node is not documented.)
• Some do not generate any warning, and
• NONE of the variables documented with the ## @var block are actually generating something in the HTML page of the class.

The last point is a particularly absurd, as the variables are shown in the left bar (the "explorer" view?) but they're not there in the actual class description page.

[albert-github]

I tried with a small Doxyfile (just GENERTAE_TREEVIEW= YES set) but I didn't get the the variables anywhere just some wanings like:

warning: documented symbol 'aa.Node::visualizer' was not declared or defined.

• Can you please attach a, small, self contained example (source+configuration file in a, compressed, tar or zip file!) that allows us to reproduce the problem? Please don't add external links as they might not be persistent (also references to GitHub repositories are considered non persistent).

[TommyPec]

I tried with a small Doxyfile (just GENERTAE_TREEVIEW= YES set) but I didn't get the the variables anywhere just some wanings like:

warning: documented symbol 'aa.Node::visualizer' was not declared or defined.

• Can you please attach a, small, self contained example (source+configuration file in a, compressed, tar or zip file!) that allows us to reproduce the problem? Please don't add external links as they might not be persistent (also references to GitHub repositories are considered non persistent).

I'll try to slim down the ns-3 project down to the only essential parts to see the issue.

[doxygen]

This issue was previously marked 'fixed but not released',
which means it should be fixed in doxygen version 1.13.0.
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).