On Mon, 03 Jun 2024, Maxime Ripard <mripard@xxxxxxxxxx> wrote: > Hi Jani, > > On Fri, May 31, 2024 at 09:43:16PM GMT, Jani Nikula wrote: >> On Mon, 27 May 2024, Maxime Ripard <mripard@xxxxxxxxxx> wrote: >> > Let me know what you think, >> >> Sorry to report that this series generates a bunch of kernel-doc >> warnings in include/drm/drm_connector.h. Documenting nested struct >> members doesn't work as smoothly as you'd expect: >> >> ../include/drm/drm_connector.h:1138: warning: Excess struct member 'broadcast_rgb' description in 'drm_connector_state' >> ../include/drm/drm_connector.h:1138: warning: Excess struct member 'infoframes' description in 'drm_connector_state' >> ../include/drm/drm_connector.h:1138: warning: Excess struct member 'avi' description in 'drm_connector_state' >> ../include/drm/drm_connector.h:1138: warning: Excess struct member 'hdr_drm' description in 'drm_connector_state' >> ../include/drm/drm_connector.h:1138: warning: Excess struct member 'spd' description in 'drm_connector_state' >> ../include/drm/drm_connector.h:1138: warning: Excess struct member 'vendor' description in 'drm_connector_state' >> ../include/drm/drm_connector.h:1138: warning: Excess struct member 'is_limited_range' description in 'drm_connector_state' >> ../include/drm/drm_connector.h:1138: warning: Excess struct member 'output_bpc' description in 'drm_connector_state' >> ../include/drm/drm_connector.h:1138: warning: Excess struct member 'output_format' description in 'drm_connector_state' >> ../include/drm/drm_connector.h:1138: warning: Excess struct member 'tmds_char_rate' description in 'drm_connector_state' >> ../include/drm/drm_connector.h:2112: warning: Excess struct member 'vendor' description in 'drm_connector' >> ../include/drm/drm_connector.h:2112: warning: Excess struct member 'product' description in 'drm_connector' >> ../include/drm/drm_connector.h:2112: warning: Excess struct member 'supported_formats' description in 'drm_connector' >> ../include/drm/drm_connector.h:2112: warning: Excess struct member 'infoframes' description in 'drm_connector' >> ../include/drm/drm_connector.h:2112: warning: Excess struct member 'lock' description in 'drm_connector' >> ../include/drm/drm_connector.h:2112: warning: Excess struct member 'audio' description in 'drm_connector' >> >> Noticed this when I was rebasing [1]. Having that merged would find >> issues in headers at build time instead of 'make htmldocs'. >> >> In the mean time, this is the quick reproducer: >> >> $ scripts/kernel-doc -none include/drm/drm_connector.h > > Thanks for the report and the reproducer. I have to admit I have no idea > how to fix it, do you have a suggestion? Some of them can be fixed by adding the parent struct name, like so: - * @broadcast_rgb: Connector property to pass the + * @hdmi.broadcast_rgb: Connector property to pass the but I think even that falls apart at some point. :( In the end might be easier to separate the struct definitions to reduce nesting. BR, Jani. -- Jani Nikula, Intel
