| Message ID | 20240106032957.1195-1-rdunlap@infradead.org (mailing list archive) |
|---|---|
| State | New, archived |
| Headers | show |
| Series | [v2] drm/vram-helper: fix kernel-doc warnings | expand |
Hi, thanks for the fix. Am 06.01.24 um 04:29 schrieb Randy Dunlap: > Remove the @funcs entry from struct drm_vram_mm to quieten the kernel-doc > warning. > > Use the "define" kernel-doc keyword and an '\' line continuation > to fix another kernel-doc warning. > > drm_gem_vram_helper.h:129: warning: missing initial short description on line: > * DRM_GEM_VRAM_PLANE_HELPER_FUNCS - > drm_gem_vram_helper.h:185: warning: Excess struct member 'funcs' description in 'drm_vram_mm' > > Signed-off-by: Randy Dunlap <rdunlap@infradead.org> > Cc: David Airlie <airlied@gmail.com> > Cc: Daniel Vetter <daniel@ffwll.ch> > Cc: dri-devel@lists.freedesktop.org > Cc: Maarten Lankhorst <maarten.lankhorst@linux.intel.com> > Cc: Maxime Ripard <mripard@kernel.org> > Cc: Thomas Zimmermann <tzimmermann@suse.de> > --- > v2: Add commit description > > base-commit: 610a9b8f49fbcf1100716370d3b5f6f884a2835a > > include/drm/drm_gem_vram_helper.h | 3 +-- > 1 file changed, 1 insertion(+), 2 deletions(-) > > diff -- a/include/drm/drm_gem_vram_helper.h b/include/drm/drm_gem_vram_helper.h > --- a/include/drm/drm_gem_vram_helper.h > +++ b/include/drm/drm_gem_vram_helper.h > @@ -126,7 +126,7 @@ drm_gem_vram_plane_helper_cleanup_fb(str > struct drm_plane_state *old_state); > > /** > - * DRM_GEM_VRAM_PLANE_HELPER_FUNCS - > + * define DRM_GEM_VRAM_PLANE_HELPER_FUNCS - \ Did something change wrt. doc syntax? I think this used to work without warnings. About this 'define': we don't use is in another docs. Can we leave it out here or is this the new syntax? Best regards Thomas > * Initializes struct drm_plane_helper_funcs for VRAM handling > * > * Drivers may use GEM BOs as VRAM helpers for the framebuffer memory. This > @@ -170,7 +170,6 @@ void drm_gem_vram_simple_display_pipe_cl > * @vram_base: Base address of the managed video memory > * @vram_size: Size of the managed video memory in bytes > * @bdev: The TTM BO device. > - * @funcs: TTM BO functions > * > * The fields &struct drm_vram_mm.vram_base and > * &struct drm_vram_mm.vrm_size are managed by VRAM MM, but are
Hi Thomas, On 1/8/24 00:57, Thomas Zimmermann wrote: > Hi, > > thanks for the fix. > > Am 06.01.24 um 04:29 schrieb Randy Dunlap: >> Remove the @funcs entry from struct drm_vram_mm to quieten the kernel-doc >> warning. >> >> Use the "define" kernel-doc keyword and an '\' line continuation >> to fix another kernel-doc warning. >> >> drm_gem_vram_helper.h:129: warning: missing initial short description on line: >> * DRM_GEM_VRAM_PLANE_HELPER_FUNCS - >> drm_gem_vram_helper.h:185: warning: Excess struct member 'funcs' description in 'drm_vram_mm' >> >> Signed-off-by: Randy Dunlap <rdunlap@infradead.org> >> Cc: David Airlie <airlied@gmail.com> >> Cc: Daniel Vetter <daniel@ffwll.ch> >> Cc: dri-devel@lists.freedesktop.org >> Cc: Maarten Lankhorst <maarten.lankhorst@linux.intel.com> >> Cc: Maxime Ripard <mripard@kernel.org> >> Cc: Thomas Zimmermann <tzimmermann@suse.de> >> --- >> v2: Add commit description >> >> base-commit: 610a9b8f49fbcf1100716370d3b5f6f884a2835a >> >> include/drm/drm_gem_vram_helper.h | 3 +-- >> 1 file changed, 1 insertion(+), 2 deletions(-) >> >> diff -- a/include/drm/drm_gem_vram_helper.h b/include/drm/drm_gem_vram_helper.h >> --- a/include/drm/drm_gem_vram_helper.h >> +++ b/include/drm/drm_gem_vram_helper.h >> @@ -126,7 +126,7 @@ drm_gem_vram_plane_helper_cleanup_fb(str >> struct drm_plane_state *old_state); >> /** >> - * DRM_GEM_VRAM_PLANE_HELPER_FUNCS - >> + * define DRM_GEM_VRAM_PLANE_HELPER_FUNCS - \ > > Did something change wrt. doc syntax? I think this used to work without warnings. About this 'define': we don't use is in another docs. Can we leave it out here or is this the new syntax? > There are no doc syntax changes that I know of. This is not new syntax. It has been around since 2014: cbb4d3e6510b ("scripts/kernel-doc: handle object-like macros") "define OBJ_LIKE_MACRO" is used 2 other times in include/drm/: drm_fb_helper.h: /** * define DRM_FB_HELPER_DEFAULT_OPS - helper define for drm drivers * * Helper define to register default implementations of drm_fb_helper * functions. To be used in struct fb_ops of drm drivers. */ drm_gem_vram_helper.h: (the file being patched here) /** * define DRM_GEM_VRAM_DRIVER - default callback functions for \ &struct drm_driver * * Drivers that use VRAM MM and GEM VRAM can use this macro to initialize * &struct drm_driver with default functions. */ > >> * Initializes struct drm_plane_helper_funcs for VRAM handling >> * >> * Drivers may use GEM BOs as VRAM helpers for the framebuffer memory. This >> @@ -170,7 +170,6 @@ void drm_gem_vram_simple_display_pipe_cl >> * @vram_base: Base address of the managed video memory >> * @vram_size: Size of the managed video memory in bytes >> * @bdev: The TTM BO device. >> - * @funcs: TTM BO functions >> * >> * The fields &struct drm_vram_mm.vram_base and >> * &struct drm_vram_mm.vrm_size are managed by VRAM MM, but are >
On Mon, Jan 08, 2024 at 01:10:12PM -0800, Randy Dunlap wrote: > Hi Thomas, > > On 1/8/24 00:57, Thomas Zimmermann wrote: > > Hi, > > > > thanks for the fix. > > > > Am 06.01.24 um 04:29 schrieb Randy Dunlap: > >> Remove the @funcs entry from struct drm_vram_mm to quieten the kernel-doc > >> warning. > >> > >> Use the "define" kernel-doc keyword and an '\' line continuation > >> to fix another kernel-doc warning. > >> > >> drm_gem_vram_helper.h:129: warning: missing initial short description on line: > >> * DRM_GEM_VRAM_PLANE_HELPER_FUNCS - > >> drm_gem_vram_helper.h:185: warning: Excess struct member 'funcs' description in 'drm_vram_mm' > >> > >> Signed-off-by: Randy Dunlap <rdunlap@infradead.org> > >> Cc: David Airlie <airlied@gmail.com> > >> Cc: Daniel Vetter <daniel@ffwll.ch> > >> Cc: dri-devel@lists.freedesktop.org > >> Cc: Maarten Lankhorst <maarten.lankhorst@linux.intel.com> > >> Cc: Maxime Ripard <mripard@kernel.org> > >> Cc: Thomas Zimmermann <tzimmermann@suse.de> > >> --- > >> v2: Add commit description > >> > >> base-commit: 610a9b8f49fbcf1100716370d3b5f6f884a2835a > >> > >> include/drm/drm_gem_vram_helper.h | 3 +-- > >> 1 file changed, 1 insertion(+), 2 deletions(-) > >> > >> diff -- a/include/drm/drm_gem_vram_helper.h b/include/drm/drm_gem_vram_helper.h > >> --- a/include/drm/drm_gem_vram_helper.h > >> +++ b/include/drm/drm_gem_vram_helper.h > >> @@ -126,7 +126,7 @@ drm_gem_vram_plane_helper_cleanup_fb(str > >> struct drm_plane_state *old_state); > >> /** > >> - * DRM_GEM_VRAM_PLANE_HELPER_FUNCS - > >> + * define DRM_GEM_VRAM_PLANE_HELPER_FUNCS - \ > > > > Did something change wrt. doc syntax? I think this used to work without warnings. About this 'define': we don't use is in another docs. Can we leave it out here or is this the new syntax? > > > > There are no doc syntax changes that I know of. This is not > new syntax. It has been around since 2014: > cbb4d3e6510b ("scripts/kernel-doc: handle object-like macros") I had no idea this exists, thanks a lot for this TIL :-) I guess the issue here is that this exists, yay, but it's not documented with the other here: https://dri.freedesktop.org/docs/drm/doc-guide/kernel-doc.html#structure-union-and-enumeration-documentation I guess a patch to kernel-doc.rst would be great. Adding some kernel-doc folks. Cheers, Sima
On Tue, 9 Jan 2024 at 13:59, Daniel Vetter <daniel@ffwll.ch> wrote: > > On Mon, Jan 08, 2024 at 01:10:12PM -0800, Randy Dunlap wrote: > > Hi Thomas, > > > > On 1/8/24 00:57, Thomas Zimmermann wrote: > > > Hi, > > > > > > thanks for the fix. > > > > > > Am 06.01.24 um 04:29 schrieb Randy Dunlap: > > >> Remove the @funcs entry from struct drm_vram_mm to quieten the kernel-doc > > >> warning. > > >> > > >> Use the "define" kernel-doc keyword and an '\' line continuation > > >> to fix another kernel-doc warning. > > >> > > >> drm_gem_vram_helper.h:129: warning: missing initial short description on line: > > >> * DRM_GEM_VRAM_PLANE_HELPER_FUNCS - > > >> drm_gem_vram_helper.h:185: warning: Excess struct member 'funcs' description in 'drm_vram_mm' > > >> > > >> Signed-off-by: Randy Dunlap <rdunlap@infradead.org> > > >> Cc: David Airlie <airlied@gmail.com> > > >> Cc: Daniel Vetter <daniel@ffwll.ch> > > >> Cc: dri-devel@lists.freedesktop.org > > >> Cc: Maarten Lankhorst <maarten.lankhorst@linux.intel.com> > > >> Cc: Maxime Ripard <mripard@kernel.org> > > >> Cc: Thomas Zimmermann <tzimmermann@suse.de> > > >> --- > > >> v2: Add commit description > > >> > > >> base-commit: 610a9b8f49fbcf1100716370d3b5f6f884a2835a > > >> > > >> include/drm/drm_gem_vram_helper.h | 3 +-- > > >> 1 file changed, 1 insertion(+), 2 deletions(-) > > >> > > >> diff -- a/include/drm/drm_gem_vram_helper.h b/include/drm/drm_gem_vram_helper.h > > >> --- a/include/drm/drm_gem_vram_helper.h > > >> +++ b/include/drm/drm_gem_vram_helper.h > > >> @@ -126,7 +126,7 @@ drm_gem_vram_plane_helper_cleanup_fb(str > > >> struct drm_plane_state *old_state); > > >> /** > > >> - * DRM_GEM_VRAM_PLANE_HELPER_FUNCS - > > >> + * define DRM_GEM_VRAM_PLANE_HELPER_FUNCS - \ > > > > > > Did something change wrt. doc syntax? I think this used to work without warnings. About this 'define': we don't use is in another docs. Can we leave it out here or is this the new syntax? > > > > > > > There are no doc syntax changes that I know of. This is not > > new syntax. It has been around since 2014: > > cbb4d3e6510b ("scripts/kernel-doc: handle object-like macros") > > I had no idea this exists, thanks a lot for this TIL :-) > > I guess the issue here is that this exists, yay, but it's not documented > with the other here: > > https://dri.freedesktop.org/docs/drm/doc-guide/kernel-doc.html#structure-union-and-enumeration-documentation > > I guess a patch to kernel-doc.rst would be great. Adding some kernel-doc > folks. Ok I went ahead and typed that patch (just we don't waste effort), just waiting for the sphinx build to finish to make sure it looks nice before I send out the patch. -Sima
On 1/9/24 05:42, Daniel Vetter wrote: > On Tue, 9 Jan 2024 at 13:59, Daniel Vetter <daniel@ffwll.ch> wrote: >> >> On Mon, Jan 08, 2024 at 01:10:12PM -0800, Randy Dunlap wrote: >>> Hi Thomas, >>> >>> On 1/8/24 00:57, Thomas Zimmermann wrote: >>>> Hi, >>>> >>>> thanks for the fix. >>>> >>>> Am 06.01.24 um 04:29 schrieb Randy Dunlap: >>>>> Remove the @funcs entry from struct drm_vram_mm to quieten the kernel-doc >>>>> warning. >>>>> >>>>> Use the "define" kernel-doc keyword and an '\' line continuation >>>>> to fix another kernel-doc warning. >>>>> >>>>> drm_gem_vram_helper.h:129: warning: missing initial short description on line: >>>>> * DRM_GEM_VRAM_PLANE_HELPER_FUNCS - >>>>> drm_gem_vram_helper.h:185: warning: Excess struct member 'funcs' description in 'drm_vram_mm' >>>>> >>>>> Signed-off-by: Randy Dunlap <rdunlap@infradead.org> >>>>> Cc: David Airlie <airlied@gmail.com> >>>>> Cc: Daniel Vetter <daniel@ffwll.ch> >>>>> Cc: dri-devel@lists.freedesktop.org >>>>> Cc: Maarten Lankhorst <maarten.lankhorst@linux.intel.com> >>>>> Cc: Maxime Ripard <mripard@kernel.org> >>>>> Cc: Thomas Zimmermann <tzimmermann@suse.de> >>>>> --- >>>>> v2: Add commit description >>>>> >>>>> base-commit: 610a9b8f49fbcf1100716370d3b5f6f884a2835a >>>>> >>>>> include/drm/drm_gem_vram_helper.h | 3 +-- >>>>> 1 file changed, 1 insertion(+), 2 deletions(-) >>>>> >>>>> diff -- a/include/drm/drm_gem_vram_helper.h b/include/drm/drm_gem_vram_helper.h >>>>> --- a/include/drm/drm_gem_vram_helper.h >>>>> +++ b/include/drm/drm_gem_vram_helper.h >>>>> @@ -126,7 +126,7 @@ drm_gem_vram_plane_helper_cleanup_fb(str >>>>> struct drm_plane_state *old_state); >>>>> /** >>>>> - * DRM_GEM_VRAM_PLANE_HELPER_FUNCS - >>>>> + * define DRM_GEM_VRAM_PLANE_HELPER_FUNCS - \ >>>> >>>> Did something change wrt. doc syntax? I think this used to work without warnings. About this 'define': we don't use is in another docs. Can we leave it out here or is this the new syntax? >>>> >>> >>> There are no doc syntax changes that I know of. This is not >>> new syntax. It has been around since 2014: >>> cbb4d3e6510b ("scripts/kernel-doc: handle object-like macros") >> >> I had no idea this exists, thanks a lot for this TIL :-) >> >> I guess the issue here is that this exists, yay, but it's not documented >> with the other here: >> >> https://dri.freedesktop.org/docs/drm/doc-guide/kernel-doc.html#structure-union-and-enumeration-documentation >> >> I guess a patch to kernel-doc.rst would be great. Adding some kernel-doc >> folks. > > Ok I went ahead and typed that patch (just we don't waste effort), > just waiting for the sphinx build to finish to make sure it looks nice > before I send out the patch. > -Sima I sent one a few days ago: https://lore.kernel.org/lkml/20240107012400.32587-1-rdunlap@infradead.org/
On Tue, 9 Jan 2024 at 16:23, Randy Dunlap <rdunlap@infradead.org> wrote: > > > > On 1/9/24 05:42, Daniel Vetter wrote: > > On Tue, 9 Jan 2024 at 13:59, Daniel Vetter <daniel@ffwll.ch> wrote: > >> > >> On Mon, Jan 08, 2024 at 01:10:12PM -0800, Randy Dunlap wrote: > >>> Hi Thomas, > >>> > >>> On 1/8/24 00:57, Thomas Zimmermann wrote: > >>>> Hi, > >>>> > >>>> thanks for the fix. > >>>> > >>>> Am 06.01.24 um 04:29 schrieb Randy Dunlap: > >>>>> Remove the @funcs entry from struct drm_vram_mm to quieten the kernel-doc > >>>>> warning. > >>>>> > >>>>> Use the "define" kernel-doc keyword and an '\' line continuation > >>>>> to fix another kernel-doc warning. > >>>>> > >>>>> drm_gem_vram_helper.h:129: warning: missing initial short description on line: > >>>>> * DRM_GEM_VRAM_PLANE_HELPER_FUNCS - > >>>>> drm_gem_vram_helper.h:185: warning: Excess struct member 'funcs' description in 'drm_vram_mm' > >>>>> > >>>>> Signed-off-by: Randy Dunlap <rdunlap@infradead.org> > >>>>> Cc: David Airlie <airlied@gmail.com> > >>>>> Cc: Daniel Vetter <daniel@ffwll.ch> > >>>>> Cc: dri-devel@lists.freedesktop.org > >>>>> Cc: Maarten Lankhorst <maarten.lankhorst@linux.intel.com> > >>>>> Cc: Maxime Ripard <mripard@kernel.org> > >>>>> Cc: Thomas Zimmermann <tzimmermann@suse.de> > >>>>> --- > >>>>> v2: Add commit description > >>>>> > >>>>> base-commit: 610a9b8f49fbcf1100716370d3b5f6f884a2835a > >>>>> > >>>>> include/drm/drm_gem_vram_helper.h | 3 +-- > >>>>> 1 file changed, 1 insertion(+), 2 deletions(-) > >>>>> > >>>>> diff -- a/include/drm/drm_gem_vram_helper.h b/include/drm/drm_gem_vram_helper.h > >>>>> --- a/include/drm/drm_gem_vram_helper.h > >>>>> +++ b/include/drm/drm_gem_vram_helper.h > >>>>> @@ -126,7 +126,7 @@ drm_gem_vram_plane_helper_cleanup_fb(str > >>>>> struct drm_plane_state *old_state); > >>>>> /** > >>>>> - * DRM_GEM_VRAM_PLANE_HELPER_FUNCS - > >>>>> + * define DRM_GEM_VRAM_PLANE_HELPER_FUNCS - \ > >>>> > >>>> Did something change wrt. doc syntax? I think this used to work without warnings. About this 'define': we don't use is in another docs. Can we leave it out here or is this the new syntax? > >>>> > >>> > >>> There are no doc syntax changes that I know of. This is not > >>> new syntax. It has been around since 2014: > >>> cbb4d3e6510b ("scripts/kernel-doc: handle object-like macros") > >> > >> I had no idea this exists, thanks a lot for this TIL :-) > >> > >> I guess the issue here is that this exists, yay, but it's not documented > >> with the other here: > >> > >> https://dri.freedesktop.org/docs/drm/doc-guide/kernel-doc.html#structure-union-and-enumeration-documentation > >> > >> I guess a patch to kernel-doc.rst would be great. Adding some kernel-doc > >> folks. > > > > Ok I went ahead and typed that patch (just we don't waste effort), > > just waiting for the sphinx build to finish to make sure it looks nice > > before I send out the patch. > > -Sima > > I sent one a few days ago: > > https://lore.kernel.org/lkml/20240107012400.32587-1-rdunlap@infradead.org/ Could you please also add documentation for function-like macros, since that's also missing? With that acked-by: me. Cheers!
On 1/9/24 07:25, Daniel Vetter wrote: > On Tue, 9 Jan 2024 at 16:23, Randy Dunlap <rdunlap@infradead.org> wrote: >> >> >> >> On 1/9/24 05:42, Daniel Vetter wrote: >>> On Tue, 9 Jan 2024 at 13:59, Daniel Vetter <daniel@ffwll.ch> wrote: >>>> >>>> On Mon, Jan 08, 2024 at 01:10:12PM -0800, Randy Dunlap wrote: >>>>> Hi Thomas, >>>>> >>>>> On 1/8/24 00:57, Thomas Zimmermann wrote: >>>>>> Hi, >>>>>> >>>>>> thanks for the fix. >>>>>> >>>>>> Am 06.01.24 um 04:29 schrieb Randy Dunlap: >>>>>>> Remove the @funcs entry from struct drm_vram_mm to quieten the kernel-doc >>>>>>> warning. >>>>>>> >>>>>>> Use the "define" kernel-doc keyword and an '\' line continuation >>>>>>> to fix another kernel-doc warning. >>>>>>> >>>>>>> drm_gem_vram_helper.h:129: warning: missing initial short description on line: >>>>>>> * DRM_GEM_VRAM_PLANE_HELPER_FUNCS - >>>>>>> drm_gem_vram_helper.h:185: warning: Excess struct member 'funcs' description in 'drm_vram_mm' >>>>>>> >>>>>>> Signed-off-by: Randy Dunlap <rdunlap@infradead.org> >>>>>>> Cc: David Airlie <airlied@gmail.com> >>>>>>> Cc: Daniel Vetter <daniel@ffwll.ch> >>>>>>> Cc: dri-devel@lists.freedesktop.org >>>>>>> Cc: Maarten Lankhorst <maarten.lankhorst@linux.intel.com> >>>>>>> Cc: Maxime Ripard <mripard@kernel.org> >>>>>>> Cc: Thomas Zimmermann <tzimmermann@suse.de> >>>>>>> --- >>>>>>> v2: Add commit description >>>>>>> >>>>>>> base-commit: 610a9b8f49fbcf1100716370d3b5f6f884a2835a >>>>>>> >>>>>>> include/drm/drm_gem_vram_helper.h | 3 +-- >>>>>>> 1 file changed, 1 insertion(+), 2 deletions(-) >>>>>>> >>>>>>> diff -- a/include/drm/drm_gem_vram_helper.h b/include/drm/drm_gem_vram_helper.h >>>>>>> --- a/include/drm/drm_gem_vram_helper.h >>>>>>> +++ b/include/drm/drm_gem_vram_helper.h >>>>>>> @@ -126,7 +126,7 @@ drm_gem_vram_plane_helper_cleanup_fb(str >>>>>>> struct drm_plane_state *old_state); >>>>>>> /** >>>>>>> - * DRM_GEM_VRAM_PLANE_HELPER_FUNCS - >>>>>>> + * define DRM_GEM_VRAM_PLANE_HELPER_FUNCS - \ >>>>>> >>>>>> Did something change wrt. doc syntax? I think this used to work without warnings. About this 'define': we don't use is in another docs. Can we leave it out here or is this the new syntax? >>>>>> >>>>> >>>>> There are no doc syntax changes that I know of. This is not >>>>> new syntax. It has been around since 2014: >>>>> cbb4d3e6510b ("scripts/kernel-doc: handle object-like macros") >>>> >>>> I had no idea this exists, thanks a lot for this TIL :-) >>>> >>>> I guess the issue here is that this exists, yay, but it's not documented >>>> with the other here: >>>> >>>> https://dri.freedesktop.org/docs/drm/doc-guide/kernel-doc.html#structure-union-and-enumeration-documentation >>>> >>>> I guess a patch to kernel-doc.rst would be great. Adding some kernel-doc >>>> folks. >>> >>> Ok I went ahead and typed that patch (just we don't waste effort), >>> just waiting for the sphinx build to finish to make sure it looks nice >>> before I send out the patch. >>> -Sima >> >> I sent one a few days ago: >> >> https://lore.kernel.org/lkml/20240107012400.32587-1-rdunlap@infradead.org/ > > Could you please also add documentation for function-like macros, > since that's also missing? With that acked-by: me. > > Cheers! This is already present: Function documentation ---------------------- The general format of a function and function-like macro kernel-doc comment is:: /** * function_name() - Brief description of function. * @arg1: Describe the first argument. * @arg2: Describe the second argument. * One can provide multiple line descriptions * for arguments. but the way that you did it makes sense also.
On Tue, 9 Jan 2024 at 16:29, Randy Dunlap <rdunlap@infradead.org> wrote: > > > > On 1/9/24 07:25, Daniel Vetter wrote: > > On Tue, 9 Jan 2024 at 16:23, Randy Dunlap <rdunlap@infradead.org> wrote: > >> > >> > >> > >> On 1/9/24 05:42, Daniel Vetter wrote: > >>> On Tue, 9 Jan 2024 at 13:59, Daniel Vetter <daniel@ffwll.ch> wrote: > >>>> > >>>> On Mon, Jan 08, 2024 at 01:10:12PM -0800, Randy Dunlap wrote: > >>>>> Hi Thomas, > >>>>> > >>>>> On 1/8/24 00:57, Thomas Zimmermann wrote: > >>>>>> Hi, > >>>>>> > >>>>>> thanks for the fix. > >>>>>> > >>>>>> Am 06.01.24 um 04:29 schrieb Randy Dunlap: > >>>>>>> Remove the @funcs entry from struct drm_vram_mm to quieten the kernel-doc > >>>>>>> warning. > >>>>>>> > >>>>>>> Use the "define" kernel-doc keyword and an '\' line continuation > >>>>>>> to fix another kernel-doc warning. > >>>>>>> > >>>>>>> drm_gem_vram_helper.h:129: warning: missing initial short description on line: > >>>>>>> * DRM_GEM_VRAM_PLANE_HELPER_FUNCS - > >>>>>>> drm_gem_vram_helper.h:185: warning: Excess struct member 'funcs' description in 'drm_vram_mm' > >>>>>>> > >>>>>>> Signed-off-by: Randy Dunlap <rdunlap@infradead.org> > >>>>>>> Cc: David Airlie <airlied@gmail.com> > >>>>>>> Cc: Daniel Vetter <daniel@ffwll.ch> > >>>>>>> Cc: dri-devel@lists.freedesktop.org > >>>>>>> Cc: Maarten Lankhorst <maarten.lankhorst@linux.intel.com> > >>>>>>> Cc: Maxime Ripard <mripard@kernel.org> > >>>>>>> Cc: Thomas Zimmermann <tzimmermann@suse.de> > >>>>>>> --- > >>>>>>> v2: Add commit description > >>>>>>> > >>>>>>> base-commit: 610a9b8f49fbcf1100716370d3b5f6f884a2835a > >>>>>>> > >>>>>>> include/drm/drm_gem_vram_helper.h | 3 +-- > >>>>>>> 1 file changed, 1 insertion(+), 2 deletions(-) > >>>>>>> > >>>>>>> diff -- a/include/drm/drm_gem_vram_helper.h b/include/drm/drm_gem_vram_helper.h > >>>>>>> --- a/include/drm/drm_gem_vram_helper.h > >>>>>>> +++ b/include/drm/drm_gem_vram_helper.h > >>>>>>> @@ -126,7 +126,7 @@ drm_gem_vram_plane_helper_cleanup_fb(str > >>>>>>> struct drm_plane_state *old_state); > >>>>>>> /** > >>>>>>> - * DRM_GEM_VRAM_PLANE_HELPER_FUNCS - > >>>>>>> + * define DRM_GEM_VRAM_PLANE_HELPER_FUNCS - \ > >>>>>> > >>>>>> Did something change wrt. doc syntax? I think this used to work without warnings. About this 'define': we don't use is in another docs. Can we leave it out here or is this the new syntax? > >>>>>> > >>>>> > >>>>> There are no doc syntax changes that I know of. This is not > >>>>> new syntax. It has been around since 2014: > >>>>> cbb4d3e6510b ("scripts/kernel-doc: handle object-like macros") > >>>> > >>>> I had no idea this exists, thanks a lot for this TIL :-) > >>>> > >>>> I guess the issue here is that this exists, yay, but it's not documented > >>>> with the other here: > >>>> > >>>> https://dri.freedesktop.org/docs/drm/doc-guide/kernel-doc.html#structure-union-and-enumeration-documentation > >>>> > >>>> I guess a patch to kernel-doc.rst would be great. Adding some kernel-doc > >>>> folks. > >>> > >>> Ok I went ahead and typed that patch (just we don't waste effort), > >>> just waiting for the sphinx build to finish to make sure it looks nice > >>> before I send out the patch. > >>> -Sima > >> > >> I sent one a few days ago: > >> > >> https://lore.kernel.org/lkml/20240107012400.32587-1-rdunlap@infradead.org/ > > > > Could you please also add documentation for function-like macros, > > since that's also missing? With that acked-by: me. > > > > Cheers! > > This is already present: > > Function documentation > ---------------------- > > The general format of a function and function-like macro kernel-doc comment is:: > > /** > * function_name() - Brief description of function. > * @arg1: Describe the first argument. > * @arg2: Describe the second argument. > * One can provide multiple line descriptions > * for arguments. > > > but the way that you did it makes sense also. Ah missed that it includes wording for function-like macros. On your patch as-is: Acked-by: Daniel Vetter <daniel.vetter@ffwll.ch>
diff -- a/include/drm/drm_gem_vram_helper.h b/include/drm/drm_gem_vram_helper.h --- a/include/drm/drm_gem_vram_helper.h +++ b/include/drm/drm_gem_vram_helper.h @@ -126,7 +126,7 @@ drm_gem_vram_plane_helper_cleanup_fb(str struct drm_plane_state *old_state); /** - * DRM_GEM_VRAM_PLANE_HELPER_FUNCS - + * define DRM_GEM_VRAM_PLANE_HELPER_FUNCS - \ * Initializes struct drm_plane_helper_funcs for VRAM handling * * Drivers may use GEM BOs as VRAM helpers for the framebuffer memory. This @@ -170,7 +170,6 @@ void drm_gem_vram_simple_display_pipe_cl * @vram_base: Base address of the managed video memory * @vram_size: Size of the managed video memory in bytes * @bdev: The TTM BO device. - * @funcs: TTM BO functions * * The fields &struct drm_vram_mm.vram_base and * &struct drm_vram_mm.vrm_size are managed by VRAM MM, but are
Remove the @funcs entry from struct drm_vram_mm to quieten the kernel-doc warning. Use the "define" kernel-doc keyword and an '\' line continuation to fix another kernel-doc warning. drm_gem_vram_helper.h:129: warning: missing initial short description on line: * DRM_GEM_VRAM_PLANE_HELPER_FUNCS - drm_gem_vram_helper.h:185: warning: Excess struct member 'funcs' description in 'drm_vram_mm' Signed-off-by: Randy Dunlap <rdunlap@infradead.org> Cc: David Airlie <airlied@gmail.com> Cc: Daniel Vetter <daniel@ffwll.ch> Cc: dri-devel@lists.freedesktop.org Cc: Maarten Lankhorst <maarten.lankhorst@linux.intel.com> Cc: Maxime Ripard <mripard@kernel.org> Cc: Thomas Zimmermann <tzimmermann@suse.de> --- v2: Add commit description base-commit: 610a9b8f49fbcf1100716370d3b5f6f884a2835a include/drm/drm_gem_vram_helper.h | 3 +-- 1 file changed, 1 insertion(+), 2 deletions(-)