Re: [Intel-gfx] [PATCH v2 01/39] drm/i915/gvt: Fix kernel-doc for intel_gvt_switch_mmio()

[Mauro Carvalho Chehab <mauro.chehab@linux.intel.com>]

On Wed, 13 Jul 2022 18:00:59 -0400
Rodrigo Vivi <rodrigo.vivi@intel.com> wrote:

> On Wed, Jul 13, 2022 at 05:54:44PM -0400, Rodrigo Vivi wrote:
> > On Wed, Jul 13, 2022 at 09:11:49AM +0100, Mauro Carvalho Chehab wrote:  
> > > From: Jiapeng Chong <jiapeng.chong@linux.alibaba.com>
> > > 
> > > Fix the following W=1 kernel warnings:
> > > 
> > > drivers/gpu/drm/i915/gvt/mmio_context.c:560: warning: expecting
> > > prototype for intel_gvt_switch_render_mmio(). Prototype was for
> > > intel_gvt_switch_mmio() instead.
> > > 
> > > Reported-by: Abaci Robot <abaci@linux.alibaba.com>
> > > Signed-off-by: Jiapeng Chong <jiapeng.chong@linux.alibaba.com>
> > > Acked-by: Zhenyu Wang <zhenyuw@linux.intel.com>
> > > Signed-off-by: Mauro Carvalho Chehab <mchehab@kernel.org>  
> > 
> > Reviewed-by: Rodrigo Vivi <rodrigo.vivi@intel.com>  
> 
> I actually changed my mind after seeing that in most cases you use "()"
> for the functions and you didn't use for this case...

The documentation build system handles both ways equally, and there's
no consensus kernel-wide about what would be the preferred way[1].

Also, at the html (or pdf) output, they'll all look the same. So, no
difference in practice at the produced documentation.

[1] The current count (using drm-tip 2022y-07m-12d-21h-47m-27s) as basis,
    is:

	$ git ls-files|xargs grep -Pzo "\/\*\*\n \* [_a-zA-Z0-9]+ -" |wc -l
	36680
	$ git ls-files|xargs grep -Pzo "\/\*\*\n \* [_a-zA-Z0-9]+\s*\(\) -" |wc -l
	12068

    So, 48748 documented functions, being ~25% with parenthesis, 
    and ~75% without it.

    Under drivers/gpu, the numbers are:

	$ git ls-files|grep drivers/gpu/|xargs grep -Pzo "\/\*\*\n \* [_a-zA-Z0-9]+\s*\(\) -" |wc -l
	480
	mchehab@sal /new_devel/v4l/tmp $ git ls-files|grep drivers/gpu/|xargs grep -Pzo "\/\*\*\n \* [_a-zA-Z0-9]+ -" |wc -l
	4046

> which one should we pick for consistency?

Yeah, it is nicer to use the same way everywhere. Btw, on media, I was
enforcing one way at the beginning, but I ended giving up doing that
as it was too many efforts for too little. Nowadays, half of media
function declarations have parenthesis, half doesn't.

Anyway, this is what we have at i915 driver, before this series:

	$ grep -Pzo "\/\*\*\n \* [_a-zA-Z0-9]+\s*\(\) -" $(find drivers/gpu/drm/i915 -type f)|wc -l
	53
	$ grep -Pzo "\/\*\*\n \* [_a-zA-Z0-9]+ -" $(find drivers/gpu/drm/i915 -type f)|wc -l
	542

This series include 3 functions with "()" (on patches 1 and 3, both
authored by Jiapeng, and 11 functions without it on my own patches.

I'll change those two patches to remove the "()" for consistency.

I guess I'll add a patch at the end changing the other 53 functions
to drop "()".

Regards,
Mauro