diff mbox series

[v4,10/27] video: fix some kernel-doc markups

Message ID 21661aed9892a1bacc7ef76a5dc9f5c7b37f5d8f.1605521731.git.mchehab+huawei@kernel.org (mailing list archive)
State New
Headers show
Series Fix several bad kernel-doc markups | expand

Commit Message

Mauro Carvalho Chehab Nov. 16, 2020, 10:18 a.m. UTC
Some identifiers have different names between their prototypes
and the kernel-doc markup.

Signed-off-by: Mauro Carvalho Chehab <mchehab+huawei@kernel.org>
---
 drivers/video/fbdev/core/fbcmap.c | 2 +-
 drivers/video/hdmi.c              | 3 ++-
 2 files changed, 3 insertions(+), 2 deletions(-)

Comments

Daniel Vetter Nov. 16, 2020, 3:36 p.m. UTC | #1
On Mon, Nov 16, 2020 at 11:18:06AM +0100, Mauro Carvalho Chehab wrote:
> Some identifiers have different names between their prototypes
> and the kernel-doc markup.
> 
> Signed-off-by: Mauro Carvalho Chehab <mchehab+huawei@kernel.org>

Acked-by: Daniel Vetter <daniel.vetter@ffwll.ch>

I'm assuming you're sending a pull request for this.
-Daniel

> ---
>  drivers/video/fbdev/core/fbcmap.c | 2 +-
>  drivers/video/hdmi.c              | 3 ++-
>  2 files changed, 3 insertions(+), 2 deletions(-)
> 
> diff --git a/drivers/video/fbdev/core/fbcmap.c b/drivers/video/fbdev/core/fbcmap.c
> index e5ae33c1a8e8..757d5c3f620b 100644
> --- a/drivers/video/fbdev/core/fbcmap.c
> +++ b/drivers/video/fbdev/core/fbcmap.c
> @@ -59,41 +59,41 @@ static u16 blue16[] __read_mostly = {
>      0x0000, 0xaaaa, 0x0000, 0xaaaa, 0x0000, 0xaaaa, 0x0000, 0xaaaa,
>      0x5555, 0xffff, 0x5555, 0xffff, 0x5555, 0xffff, 0x5555, 0xffff
>  };
>  
>  static const struct fb_cmap default_2_colors = {
>      .len=2, .red=red2, .green=green2, .blue=blue2
>  };
>  static const struct fb_cmap default_8_colors = {
>      .len=8, .red=red8, .green=green8, .blue=blue8
>  };
>  static const struct fb_cmap default_4_colors = {
>      .len=4, .red=red4, .green=green4, .blue=blue4
>  };
>  static const struct fb_cmap default_16_colors = {
>      .len=16, .red=red16, .green=green16, .blue=blue16
>  };
>  
>  
>  
>  /**
> - *	fb_alloc_cmap - allocate a colormap
> + *	fb_alloc_cmap_gfp - allocate a colormap
>   *	@cmap: frame buffer colormap structure
>   *	@len: length of @cmap
>   *	@transp: boolean, 1 if there is transparency, 0 otherwise
>   *	@flags: flags for kmalloc memory allocation
>   *
>   *	Allocates memory for a colormap @cmap.  @len is the
>   *	number of entries in the palette.
>   *
>   *	Returns negative errno on error, or zero on success.
>   *
>   */
>  
>  int fb_alloc_cmap_gfp(struct fb_cmap *cmap, int len, int transp, gfp_t flags)
>  {
>  	int size = len * sizeof(u16);
>  	int ret = -ENOMEM;
>  
>  	flags |= __GFP_NOWARN;
>  
>  	if (cmap->len != len) {
> diff --git a/drivers/video/hdmi.c b/drivers/video/hdmi.c
> index 1e4cb63d0d11..947be761dfa4 100644
> --- a/drivers/video/hdmi.c
> +++ b/drivers/video/hdmi.c
> @@ -1675,41 +1675,42 @@ static int hdmi_audio_infoframe_unpack(struct hdmi_audio_infoframe *frame,
>  
>  	ret = hdmi_audio_infoframe_init(frame);
>  	if (ret)
>  		return ret;
>  
>  	ptr += HDMI_INFOFRAME_HEADER_SIZE;
>  
>  	frame->channels = ptr[0] & 0x7;
>  	frame->coding_type = (ptr[0] >> 4) & 0xf;
>  	frame->sample_size = ptr[1] & 0x3;
>  	frame->sample_frequency = (ptr[1] >> 2) & 0x7;
>  	frame->coding_type_ext = ptr[2] & 0x1f;
>  	frame->channel_allocation = ptr[3];
>  	frame->level_shift_value = (ptr[4] >> 3) & 0xf;
>  	frame->downmix_inhibit = ptr[4] & 0x80 ? true : false;
>  
>  	return 0;
>  }
>  
>  /**
> - * hdmi_vendor_infoframe_unpack() - unpack binary buffer to a HDMI vendor infoframe
> + * hdmi_vendor_any_infoframe_unpack() - unpack binary buffer to a HDMI
> + * 	vendor infoframe
>   * @frame: HDMI Vendor infoframe
>   * @buffer: source buffer
>   * @size: size of buffer
>   *
>   * Unpacks the information contained in binary @buffer into a structured
>   * @frame of the HDMI Vendor information frame.
>   * Also verifies the checksum as required by section 5.3.5 of the HDMI 1.4
>   * specification.
>   *
>   * Returns 0 on success or a negative error code on failure.
>   */
>  static int
>  hdmi_vendor_any_infoframe_unpack(union hdmi_vendor_any_infoframe *frame,
>  				 const void *buffer, size_t size)
>  {
>  	const u8 *ptr = buffer;
>  	size_t length;
>  	int ret;
>  	u8 hdmi_video_format;
>  	struct hdmi_vendor_infoframe *hvf = &frame->hdmi;
> -- 
> 2.28.0
>
Mauro Carvalho Chehab Nov. 16, 2020, 4:38 p.m. UTC | #2
Em Mon, 16 Nov 2020 16:36:06 +0100
Daniel Vetter <daniel@ffwll.ch> escreveu:

> On Mon, Nov 16, 2020 at 11:18:06AM +0100, Mauro Carvalho Chehab wrote:
> > Some identifiers have different names between their prototypes
> > and the kernel-doc markup.
> > 
> > Signed-off-by: Mauro Carvalho Chehab <mchehab+huawei@kernel.org>  
> 
> Acked-by: Daniel Vetter <daniel.vetter@ffwll.ch>
> 
> I'm assuming you're sending a pull request for this.

Feel free to just merge it via your tree. Patches here are pretty
much independent ;-)

> -Daniel
> 
> > ---
> >  drivers/video/fbdev/core/fbcmap.c | 2 +-
> >  drivers/video/hdmi.c              | 3 ++-
> >  2 files changed, 3 insertions(+), 2 deletions(-)
> > 
> > diff --git a/drivers/video/fbdev/core/fbcmap.c b/drivers/video/fbdev/core/fbcmap.c
> > index e5ae33c1a8e8..757d5c3f620b 100644
> > --- a/drivers/video/fbdev/core/fbcmap.c
> > +++ b/drivers/video/fbdev/core/fbcmap.c
> > @@ -59,41 +59,41 @@ static u16 blue16[] __read_mostly = {
> >      0x0000, 0xaaaa, 0x0000, 0xaaaa, 0x0000, 0xaaaa, 0x0000, 0xaaaa,
> >      0x5555, 0xffff, 0x5555, 0xffff, 0x5555, 0xffff, 0x5555, 0xffff
> >  };
> >  
> >  static const struct fb_cmap default_2_colors = {
> >      .len=2, .red=red2, .green=green2, .blue=blue2
> >  };
> >  static const struct fb_cmap default_8_colors = {
> >      .len=8, .red=red8, .green=green8, .blue=blue8
> >  };
> >  static const struct fb_cmap default_4_colors = {
> >      .len=4, .red=red4, .green=green4, .blue=blue4
> >  };
> >  static const struct fb_cmap default_16_colors = {
> >      .len=16, .red=red16, .green=green16, .blue=blue16
> >  };
> >  
> >  
> >  
> >  /**
> > - *	fb_alloc_cmap - allocate a colormap
> > + *	fb_alloc_cmap_gfp - allocate a colormap
> >   *	@cmap: frame buffer colormap structure
> >   *	@len: length of @cmap
> >   *	@transp: boolean, 1 if there is transparency, 0 otherwise
> >   *	@flags: flags for kmalloc memory allocation
> >   *
> >   *	Allocates memory for a colormap @cmap.  @len is the
> >   *	number of entries in the palette.
> >   *
> >   *	Returns negative errno on error, or zero on success.
> >   *
> >   */
> >  
> >  int fb_alloc_cmap_gfp(struct fb_cmap *cmap, int len, int transp, gfp_t flags)
> >  {
> >  	int size = len * sizeof(u16);
> >  	int ret = -ENOMEM;
> >  
> >  	flags |= __GFP_NOWARN;
> >  
> >  	if (cmap->len != len) {
> > diff --git a/drivers/video/hdmi.c b/drivers/video/hdmi.c
> > index 1e4cb63d0d11..947be761dfa4 100644
> > --- a/drivers/video/hdmi.c
> > +++ b/drivers/video/hdmi.c
> > @@ -1675,41 +1675,42 @@ static int hdmi_audio_infoframe_unpack(struct hdmi_audio_infoframe *frame,
> >  
> >  	ret = hdmi_audio_infoframe_init(frame);
> >  	if (ret)
> >  		return ret;
> >  
> >  	ptr += HDMI_INFOFRAME_HEADER_SIZE;
> >  
> >  	frame->channels = ptr[0] & 0x7;
> >  	frame->coding_type = (ptr[0] >> 4) & 0xf;
> >  	frame->sample_size = ptr[1] & 0x3;
> >  	frame->sample_frequency = (ptr[1] >> 2) & 0x7;
> >  	frame->coding_type_ext = ptr[2] & 0x1f;
> >  	frame->channel_allocation = ptr[3];
> >  	frame->level_shift_value = (ptr[4] >> 3) & 0xf;
> >  	frame->downmix_inhibit = ptr[4] & 0x80 ? true : false;
> >  
> >  	return 0;
> >  }
> >  
> >  /**
> > - * hdmi_vendor_infoframe_unpack() - unpack binary buffer to a HDMI vendor infoframe
> > + * hdmi_vendor_any_infoframe_unpack() - unpack binary buffer to a HDMI
> > + * 	vendor infoframe
> >   * @frame: HDMI Vendor infoframe
> >   * @buffer: source buffer
> >   * @size: size of buffer
> >   *
> >   * Unpacks the information contained in binary @buffer into a structured
> >   * @frame of the HDMI Vendor information frame.
> >   * Also verifies the checksum as required by section 5.3.5 of the HDMI 1.4
> >   * specification.
> >   *
> >   * Returns 0 on success or a negative error code on failure.
> >   */
> >  static int
> >  hdmi_vendor_any_infoframe_unpack(union hdmi_vendor_any_infoframe *frame,
> >  				 const void *buffer, size_t size)
> >  {
> >  	const u8 *ptr = buffer;
> >  	size_t length;
> >  	int ret;
> >  	u8 hdmi_video_format;
> >  	struct hdmi_vendor_infoframe *hvf = &frame->hdmi;
> > -- 
> > 2.28.0
> >   
> 



Thanks,
Mauro
Daniel Vetter Nov. 16, 2020, 5:24 p.m. UTC | #3
On Mon, Nov 16, 2020 at 05:38:04PM +0100, Mauro Carvalho Chehab wrote:
> Em Mon, 16 Nov 2020 16:36:06 +0100
> Daniel Vetter <daniel@ffwll.ch> escreveu:
> 
> > On Mon, Nov 16, 2020 at 11:18:06AM +0100, Mauro Carvalho Chehab wrote:
> > > Some identifiers have different names between their prototypes
> > > and the kernel-doc markup.
> > > 
> > > Signed-off-by: Mauro Carvalho Chehab <mchehab+huawei@kernel.org>  
> > 
> > Acked-by: Daniel Vetter <daniel.vetter@ffwll.ch>
> > 
> > I'm assuming you're sending a pull request for this.
> 
> Feel free to just merge it via your tree. Patches here are pretty
> much independent ;-)

Ok I put it into drm-misc-next. I kinda assumed since there's also a huge
effort going on to shut up warnings, plus I think kerneldoc issues are
reported by a bunch of build bots nowadays. So assumed you pile this all
up.
-Daniel

> 
> > -Daniel
> > 
> > > ---
> > >  drivers/video/fbdev/core/fbcmap.c | 2 +-
> > >  drivers/video/hdmi.c              | 3 ++-
> > >  2 files changed, 3 insertions(+), 2 deletions(-)
> > > 
> > > diff --git a/drivers/video/fbdev/core/fbcmap.c b/drivers/video/fbdev/core/fbcmap.c
> > > index e5ae33c1a8e8..757d5c3f620b 100644
> > > --- a/drivers/video/fbdev/core/fbcmap.c
> > > +++ b/drivers/video/fbdev/core/fbcmap.c
> > > @@ -59,41 +59,41 @@ static u16 blue16[] __read_mostly = {
> > >      0x0000, 0xaaaa, 0x0000, 0xaaaa, 0x0000, 0xaaaa, 0x0000, 0xaaaa,
> > >      0x5555, 0xffff, 0x5555, 0xffff, 0x5555, 0xffff, 0x5555, 0xffff
> > >  };
> > >  
> > >  static const struct fb_cmap default_2_colors = {
> > >      .len=2, .red=red2, .green=green2, .blue=blue2
> > >  };
> > >  static const struct fb_cmap default_8_colors = {
> > >      .len=8, .red=red8, .green=green8, .blue=blue8
> > >  };
> > >  static const struct fb_cmap default_4_colors = {
> > >      .len=4, .red=red4, .green=green4, .blue=blue4
> > >  };
> > >  static const struct fb_cmap default_16_colors = {
> > >      .len=16, .red=red16, .green=green16, .blue=blue16
> > >  };
> > >  
> > >  
> > >  
> > >  /**
> > > - *	fb_alloc_cmap - allocate a colormap
> > > + *	fb_alloc_cmap_gfp - allocate a colormap
> > >   *	@cmap: frame buffer colormap structure
> > >   *	@len: length of @cmap
> > >   *	@transp: boolean, 1 if there is transparency, 0 otherwise
> > >   *	@flags: flags for kmalloc memory allocation
> > >   *
> > >   *	Allocates memory for a colormap @cmap.  @len is the
> > >   *	number of entries in the palette.
> > >   *
> > >   *	Returns negative errno on error, or zero on success.
> > >   *
> > >   */
> > >  
> > >  int fb_alloc_cmap_gfp(struct fb_cmap *cmap, int len, int transp, gfp_t flags)
> > >  {
> > >  	int size = len * sizeof(u16);
> > >  	int ret = -ENOMEM;
> > >  
> > >  	flags |= __GFP_NOWARN;
> > >  
> > >  	if (cmap->len != len) {
> > > diff --git a/drivers/video/hdmi.c b/drivers/video/hdmi.c
> > > index 1e4cb63d0d11..947be761dfa4 100644
> > > --- a/drivers/video/hdmi.c
> > > +++ b/drivers/video/hdmi.c
> > > @@ -1675,41 +1675,42 @@ static int hdmi_audio_infoframe_unpack(struct hdmi_audio_infoframe *frame,
> > >  
> > >  	ret = hdmi_audio_infoframe_init(frame);
> > >  	if (ret)
> > >  		return ret;
> > >  
> > >  	ptr += HDMI_INFOFRAME_HEADER_SIZE;
> > >  
> > >  	frame->channels = ptr[0] & 0x7;
> > >  	frame->coding_type = (ptr[0] >> 4) & 0xf;
> > >  	frame->sample_size = ptr[1] & 0x3;
> > >  	frame->sample_frequency = (ptr[1] >> 2) & 0x7;
> > >  	frame->coding_type_ext = ptr[2] & 0x1f;
> > >  	frame->channel_allocation = ptr[3];
> > >  	frame->level_shift_value = (ptr[4] >> 3) & 0xf;
> > >  	frame->downmix_inhibit = ptr[4] & 0x80 ? true : false;
> > >  
> > >  	return 0;
> > >  }
> > >  
> > >  /**
> > > - * hdmi_vendor_infoframe_unpack() - unpack binary buffer to a HDMI vendor infoframe
> > > + * hdmi_vendor_any_infoframe_unpack() - unpack binary buffer to a HDMI
> > > + * 	vendor infoframe
> > >   * @frame: HDMI Vendor infoframe
> > >   * @buffer: source buffer
> > >   * @size: size of buffer
> > >   *
> > >   * Unpacks the information contained in binary @buffer into a structured
> > >   * @frame of the HDMI Vendor information frame.
> > >   * Also verifies the checksum as required by section 5.3.5 of the HDMI 1.4
> > >   * specification.
> > >   *
> > >   * Returns 0 on success or a negative error code on failure.
> > >   */
> > >  static int
> > >  hdmi_vendor_any_infoframe_unpack(union hdmi_vendor_any_infoframe *frame,
> > >  				 const void *buffer, size_t size)
> > >  {
> > >  	const u8 *ptr = buffer;
> > >  	size_t length;
> > >  	int ret;
> > >  	u8 hdmi_video_format;
> > >  	struct hdmi_vendor_infoframe *hvf = &frame->hdmi;
> > > -- 
> > > 2.28.0
> > >   
> > 
> 
> 
> 
> Thanks,
> Mauro
Sam Ravnborg Nov. 16, 2020, 6:11 p.m. UTC | #4
Hi Daniel
> > Feel free to just merge it via your tree. Patches here are pretty
> > much independent ;-)
> 
> Ok I put it into drm-misc-next. I kinda assumed since there's also a huge
> effort going on to shut up warnings, plus I think kerneldoc issues are
> reported by a bunch of build bots nowadays. So assumed you pile this all
> up.

Any reason "drm: fix some kernel-doc markups" was not applied?

	Sam
Mauro Carvalho Chehab Nov. 16, 2020, 6:42 p.m. UTC | #5
Em Mon, 16 Nov 2020 18:24:04 +0100
Daniel Vetter <daniel@ffwll.ch> escreveu:

> On Mon, Nov 16, 2020 at 05:38:04PM +0100, Mauro Carvalho Chehab wrote:
> > Em Mon, 16 Nov 2020 16:36:06 +0100
> > Daniel Vetter <daniel@ffwll.ch> escreveu:
> >   
> > > On Mon, Nov 16, 2020 at 11:18:06AM +0100, Mauro Carvalho Chehab wrote:  
> > > > Some identifiers have different names between their prototypes
> > > > and the kernel-doc markup.
> > > > 
> > > > Signed-off-by: Mauro Carvalho Chehab <mchehab+huawei@kernel.org>    
> > > 
> > > Acked-by: Daniel Vetter <daniel.vetter@ffwll.ch>
> > > 
> > > I'm assuming you're sending a pull request for this.  
> > 
> > Feel free to just merge it via your tree. Patches here are pretty
> > much independent ;-)  
> 
> Ok I put it into drm-misc-next. I kinda assumed since there's also a huge
> effort going on to shut up warnings, plus I think kerneldoc issues are
> reported by a bunch of build bots nowadays. So assumed you pile this all
> up.

Currently, this doesn't generate any warnings (which, IMHO, it is a
very bad thing). The final patch on this series actually such warning. 
My plan is to have the final patch merged for Kernel 5.11.

So, at least from PoV of shut up warnings[1], this patch be either
be merged for 5.11 or earlier.

Regards,
Mauro

-

[1] Basically, if you do:

	/**
	 * foo - some foo func
	 */
	int bar(...)

the documentation will be for "bar()" function, instead of
"foo()", as Kernel-doc currently simply ignores "foo".

On several places, this is due to a typo or a function
rename, but there are a few places where a "bar()" function
got added between the kernel-doc markup and "foo()" function,
thus producing wrong docs. Don't remember if are there any
such issues under drivers/video or drivers/gpu.
Daniel Vetter Nov. 16, 2020, 7:43 p.m. UTC | #6
On Mon, Nov 16, 2020 at 07:11:12PM +0100, Sam Ravnborg wrote:
> Hi Daniel
> > > Feel free to just merge it via your tree. Patches here are pretty
> > > much independent ;-)
> > 
> > Ok I put it into drm-misc-next. I kinda assumed since there's also a huge
> > effort going on to shut up warnings, plus I think kerneldoc issues are
> > reported by a bunch of build bots nowadays. So assumed you pile this all
> > up.
> 
> Any reason "drm: fix some kernel-doc markups" was not applied?

Oh somehow I thought that one was only for i915 issues. I guess I'll take
a look.
-Daniel
diff mbox series

Patch

diff --git a/drivers/video/fbdev/core/fbcmap.c b/drivers/video/fbdev/core/fbcmap.c
index e5ae33c1a8e8..757d5c3f620b 100644
--- a/drivers/video/fbdev/core/fbcmap.c
+++ b/drivers/video/fbdev/core/fbcmap.c
@@ -59,41 +59,41 @@  static u16 blue16[] __read_mostly = {
     0x0000, 0xaaaa, 0x0000, 0xaaaa, 0x0000, 0xaaaa, 0x0000, 0xaaaa,
     0x5555, 0xffff, 0x5555, 0xffff, 0x5555, 0xffff, 0x5555, 0xffff
 };
 
 static const struct fb_cmap default_2_colors = {
     .len=2, .red=red2, .green=green2, .blue=blue2
 };
 static const struct fb_cmap default_8_colors = {
     .len=8, .red=red8, .green=green8, .blue=blue8
 };
 static const struct fb_cmap default_4_colors = {
     .len=4, .red=red4, .green=green4, .blue=blue4
 };
 static const struct fb_cmap default_16_colors = {
     .len=16, .red=red16, .green=green16, .blue=blue16
 };
 
 
 
 /**
- *	fb_alloc_cmap - allocate a colormap
+ *	fb_alloc_cmap_gfp - allocate a colormap
  *	@cmap: frame buffer colormap structure
  *	@len: length of @cmap
  *	@transp: boolean, 1 if there is transparency, 0 otherwise
  *	@flags: flags for kmalloc memory allocation
  *
  *	Allocates memory for a colormap @cmap.  @len is the
  *	number of entries in the palette.
  *
  *	Returns negative errno on error, or zero on success.
  *
  */
 
 int fb_alloc_cmap_gfp(struct fb_cmap *cmap, int len, int transp, gfp_t flags)
 {
 	int size = len * sizeof(u16);
 	int ret = -ENOMEM;
 
 	flags |= __GFP_NOWARN;
 
 	if (cmap->len != len) {
diff --git a/drivers/video/hdmi.c b/drivers/video/hdmi.c
index 1e4cb63d0d11..947be761dfa4 100644
--- a/drivers/video/hdmi.c
+++ b/drivers/video/hdmi.c
@@ -1675,41 +1675,42 @@  static int hdmi_audio_infoframe_unpack(struct hdmi_audio_infoframe *frame,
 
 	ret = hdmi_audio_infoframe_init(frame);
 	if (ret)
 		return ret;
 
 	ptr += HDMI_INFOFRAME_HEADER_SIZE;
 
 	frame->channels = ptr[0] & 0x7;
 	frame->coding_type = (ptr[0] >> 4) & 0xf;
 	frame->sample_size = ptr[1] & 0x3;
 	frame->sample_frequency = (ptr[1] >> 2) & 0x7;
 	frame->coding_type_ext = ptr[2] & 0x1f;
 	frame->channel_allocation = ptr[3];
 	frame->level_shift_value = (ptr[4] >> 3) & 0xf;
 	frame->downmix_inhibit = ptr[4] & 0x80 ? true : false;
 
 	return 0;
 }
 
 /**
- * hdmi_vendor_infoframe_unpack() - unpack binary buffer to a HDMI vendor infoframe
+ * hdmi_vendor_any_infoframe_unpack() - unpack binary buffer to a HDMI
+ * 	vendor infoframe
  * @frame: HDMI Vendor infoframe
  * @buffer: source buffer
  * @size: size of buffer
  *
  * Unpacks the information contained in binary @buffer into a structured
  * @frame of the HDMI Vendor information frame.
  * Also verifies the checksum as required by section 5.3.5 of the HDMI 1.4
  * specification.
  *
  * Returns 0 on success or a negative error code on failure.
  */
 static int
 hdmi_vendor_any_infoframe_unpack(union hdmi_vendor_any_infoframe *frame,
 				 const void *buffer, size_t size)
 {
 	const u8 *ptr = buffer;
 	size_t length;
 	int ret;
 	u8 hdmi_video_format;
 	struct hdmi_vendor_infoframe *hvf = &frame->hdmi;