Wrong doc for enum values

[oaubert]

The new treesitter engine does not capture the right documentation for values in Enums. It seems to assume that the docstring is before the enum, but misses the single-line definition+doc style, where the docstring is on the same line as the enum definition.

This produces wrong output as can be seen in the generated documentation, e.g.: https://python-vlc.readthedocs.io/en/latest/api/vlc/VideoOrient.html#vlc-videoorient

@yanns1 any idea on how to fix this?

[yanns1]

Yes, that is the assumption made in Parser.parse_doxygen_comment, it will pick up the comment before the item (considering a top-down, left-to-right reading of the source code).

We can allow for comments positioned after and on the same line for enum values by replacing lines 1391-1393 (in generator/generate.py, method parse_enums) by:

                vdocs = None
                if (
                    child.next_named_sibling is not None
                    and child.next_named_sibling.type == "comment"
                    and child.next_named_sibling.start_point[0] == child.end_point[0]
                ):
                    vdocs = clean_doxygen_comment(tsnode_text(child.next_named_sibling))
                elif (
                    child.prev_sibling is not None
                    and child.prev_sibling.type == "comment"
                ):
                    vdocs = clean_doxygen_comment(tsnode_text(child.prev_sibling))
                else:
                    vdocs = ""

The enum-enum value pairs that fall through the first case are:

libvlc_log_level LIBVLC_DEBUG
libvlc_log_level LIBVLC_NOTICE
libvlc_log_level LIBVLC_WARNING
libvlc_log_level LIBVLC_ERROR
libvlc_state_t libvlc_Buffering
libvlc_video_orient_t libvlc_video_orient_top_left
libvlc_video_orient_t libvlc_video_orient_top_right
libvlc_video_orient_t libvlc_video_orient_bottom_left
libvlc_video_orient_t libvlc_video_orient_bottom_right
libvlc_video_orient_t libvlc_video_orient_left_top
libvlc_video_orient_t libvlc_video_orient_left_bottom
libvlc_video_orient_t libvlc_video_orient_right_top
libvlc_video_orient_t libvlc_video_orient_right_bottom
libvlc_video_projection_t libvlc_video_projection_equirectangular
libvlc_video_marquee_option_t libvlc_marquee_Text
libvlc_video_logo_option_t libvlc_logo_file
libvlc_media_player_role_t libvlc_role_None
libvlc_media_player_role_t libvlc_role_Music
libvlc_media_player_role_t libvlc_role_Video
libvlc_media_player_role_t libvlc_role_Communication
libvlc_media_player_role_t libvlc_role_Game
libvlc_media_player_role_t libvlc_role_Notification
libvlc_media_player_role_t libvlc_role_Animation
libvlc_media_player_role_t libvlc_role_Production
libvlc_media_player_role_t libvlc_role_Accessibility
libvlc_media_player_role_t libvlc_role_Test

I could have change Parser.parse_doxygen_comment, but considering "after comments" may not work well for other items.

[oaubert]

Great, thanks!