[Intel-gfx] [drm-intel:for-linux-next-fixes 3/4] DockBook: drivers/gpu/drm/drm_probe_helper.c:107: warning: Excess function parameter 'dev' description in 'DRM_OUTPUT_POLL_PERIOD'

[Jani Nikula]

On Wed, 30 Sep 2015, Egbert Eich <eich at suse.com> wrote:
> Jani Nikula writes:
>  > On Wed, 30 Sep 2015, Daniel Vetter <daniel at ffwll.ch> wrote:
>  > > On Wed, Sep 30, 2015 at 05:09:04PM +0800, kbuild test robot wrote:
>  > >> tree:   git://anongit.freedesktop.org/drm-intel for-linux-next-fixes
>  > >> head:   ad96c5f13442b17fafccc30f81efae2f08351f99
>  > >> commit: 10d3a5618b3aba24d6388ccdff2d0182b72a6e8d [3/4] drm: Add a non-locking version of drm_kms_helper_poll_enable(), v2
>  > >> reproduce: make htmldocs
>  > >> 
>  > >> All warnings (new ones prefixed by >>):
>  > 
>  > Cc: Jonathan and Danilo, and including the kernel-doc in question for
>  > reference:
>  > 
>  > /**
>  >  * drm_kms_helper_poll_enable_locked - re-enable output polling.
>  >  * @dev: drm_device
>  >  *
>  >  * This function re-enables the output polling work without
>  >  * locking the mode_config mutex.
>  >  *
>  >  * This is like drm_kms_helper_poll_enable() however it is to be
>  >  * called from a context where the mode_config mutex is locked
>  >  * already.
>  >  */
>  > #define DRM_OUTPUT_POLL_PERIOD (10*HZ)
>  > void drm_kms_helper_poll_enable_locked(struct drm_device *dev)
>  > {
>  > 	...
>  > 
>  > >> >> drivers/gpu/drm/drm_probe_helper.c:107: warning: Excess function parameter 'dev' description in 'DRM_OUTPUT_POLL_PERIOD'
>  > >> >> drivers/gpu/drm/drm_probe_helper.c:107: warning: Excess function parameter 'dev' description in 'DRM_OUTPUT_POLL_PERIOD'
>  > >
>  > > I think this should be fixed by moving the DRM_OUTPUT_POLL_PERIOD #define
>  > > before the kerneldoc for drm_kms_helper_poll_enable_locked. Jani, can you
>  > > please do that fixup and check that make htmldocs is happy with it?
>  > 
>  > Can do.
>  > 
>  > However, having such #defines right above the only function that uses
>  > them is not uncommon. Since there is no documentation for
>  > DRM_OUTPUT_POLL_PERIOD, and the documentation for the function includes
>  > the function name, I am wondering if kernel-doc could be made smarter
>  > about this.
>  > 
>
> It is actually used twice in this file by two functions not immediately adjacent.
> Why not move it to the beginning of the file?

That would've been better, however I was too quick to fix it already
like Daniel suggested.

BR,
Jani.

>
> Cheers,
> 	Egbert.

-- 
Jani Nikula, Intel Open Source Technology Center