[PATCH v4 00/27]Fix several bad kernel-doc markups

[PATCH v4 00/27]Fix several bad kernel-doc markups

[Mauro Carvalho Chehab]

Kernel-doc has always be limited to a probably bad documented
rule:

The kernel-doc markups should appear *imediatelly before* the
function or data structure that it documents.

On other words, if a C file would contain something like this:

	/**
	 * foo - function foo
	 * @args: foo args
	 */
	static inline void bar(int args);

	/**
	 * bar - function bar
	 * @args: foo args
	 */
	static inline void foo(void *args);


The output (in ReST format) will be:

	.. c:function:: void bar (int args)

	   function foo

	**Parameters**

	``int args``
	  foo args


	.. c:function:: void foo (void *args)

	   function bar

	**Parameters**

	``void *args``
	  foo args

Which is clearly a wrong result.  Before this changeset, 
not even a warning is produced on such cases.

As placing such markups just before the documented
data is a common practice, on most cases this is fine.

However, as patches touch things, identifiers may be
renamed, and people may forget to update the kernel-doc
markups to follow such changes.

This has been happening for quite a while, as there are
lots of files with kernel-doc problems.

This series address those issues and add a file at the
end that will enforce that the identifier will match the
kernel-doc markup, avoiding this problem from
keep happening as time goes by.

This series is based on current upstream tree.

@maintainers: feel free to pick the patches and
apply them directly on your trees, as all patches on 
this series are independent from the other ones.

--

v4:

  - Patches got rebased and got some acks.

Mauro Carvalho Chehab (27):
  net: phy: fix kernel-doc markups
  net: datagram: fix some kernel-doc markups
  net: core: fix some kernel-doc markups
  s390: fix kernel-doc markups
  drm: fix some kernel-doc markups
  HSI: fix a kernel-doc markup
  IB: fix kernel-doc markups
  parport: fix a kernel-doc markup
  rapidio: fix kernel-doc a markup
  video: fix some kernel-doc markups
  fs: fix kernel-doc markups
  jbd2: fix kernel-doc markups
  pstore/zone: fix a kernel-doc markup
  completion: fix kernel-doc markups
  firmware: stratix10-svc: fix kernel-doc markups
  connector: fix a kernel-doc markup
  lib/crc7: fix a kernel-doc markup
  hrtimer: fix kernel-doc markups
  genirq: fix kernel-doc markups
  list: fix a typo at the kernel-doc markup
  memblock: fix kernel-doc markups
  w1: fix a kernel-doc markup
  resource: fix kernel-doc markups
  shed: fix kernel-doc markup
  mm: fix kernel-doc markups
  selftests: kselftest_harness.h: partially fix kernel-doc markups
  scripts: kernel-doc: validate kernel-doc markup with the actual names

 arch/s390/include/asm/ccwdev.h                |  2 +-
 arch/s390/include/asm/cio.h                   |  2 +-
 drivers/gpu/drm/drm_atomic_state_helper.c     |  2 +-
 drivers/gpu/drm/drm_connector.c               |  3 +-
 drivers/gpu/drm/drm_dp_helper.c               |  2 +-
 drivers/gpu/drm/drm_framebuffer.c             |  2 +-
 drivers/gpu/drm/drm_gem.c                     |  4 +-
 drivers/gpu/drm/drm_gem_vram_helper.c         |  2 +-
 drivers/gpu/drm/drm_mode_object.c             |  2 +-
 drivers/gpu/drm/drm_modes.c                   |  4 +-
 drivers/gpu/drm/drm_scdc_helper.c             |  2 +-
 drivers/gpu/drm/i915/display/intel_dpll_mgr.c |  2 +-
 drivers/gpu/drm/i915/i915_gem_evict.c         |  2 +-
 drivers/gpu/drm/i915/i915_perf.c              |  8 ++-
 drivers/gpu/drm/scheduler/sched_main.c        |  2 +-
 drivers/gpu/drm/v3d/v3d_sched.c               |  2 +-
 drivers/gpu/drm/vc4/vc4_bo.c                  |  2 +-
 drivers/hsi/hsi_core.c                        |  2 +-
 drivers/infiniband/core/cm.c                  |  5 +-
 drivers/infiniband/core/cq.c                  |  4 +-
 drivers/infiniband/core/iwpm_util.h           |  2 +-
 drivers/infiniband/core/sa_query.c            |  3 +-
 drivers/infiniband/core/verbs.c               |  4 +-
 drivers/infiniband/sw/rdmavt/ah.c             |  2 +-
 drivers/infiniband/sw/rdmavt/mcast.c          | 12 ++--
 drivers/infiniband/sw/rdmavt/qp.c             |  8 +--
 drivers/infiniband/ulp/iser/iscsi_iser.c      |  2 +-
 .../infiniband/ulp/opa_vnic/opa_vnic_encap.h  |  2 +-
 .../ulp/opa_vnic/opa_vnic_vema_iface.c        |  2 +-
 drivers/infiniband/ulp/srpt/ib_srpt.h         |  2 +-
 drivers/net/phy/mdio_bus.c                    |  2 +-
 drivers/net/phy/phy-c45.c                     |  2 +-
 drivers/net/phy/phy.c                         |  2 +-
 drivers/net/phy/phy_device.c                  |  2 +-
 drivers/net/phy/phylink.c                     |  2 +-
 drivers/parport/share.c                       |  2 +-
 drivers/rapidio/rio.c                         |  2 +-
 drivers/video/fbdev/core/fbcmap.c             |  2 +-
 drivers/video/hdmi.c                          |  3 +-
 fs/dcache.c                                   | 72 +++++++++----------
 fs/inode.c                                    |  4 +-
 fs/jbd2/journal.c                             | 34 ++++-----
 fs/jbd2/transaction.c                         | 31 ++++----
 fs/pstore/zone.c                              |  2 +-
 fs/seq_file.c                                 |  5 +-
 fs/super.c                                    | 12 ++--
 include/drm/drm_atomic_helper.h               |  4 +-
 include/drm/drm_connector.h                   |  2 +-
 include/drm/drm_device.h                      |  2 +-
 include/drm/drm_dsc.h                         |  3 +-
 include/drm/drm_gem_vram_helper.h             |  8 +--
 include/linux/completion.h                    | 10 ++-
 include/linux/connector.h                     |  2 +-
 .../firmware/intel/stratix10-svc-client.h     | 10 +--
 include/linux/hrtimer.h                       |  6 +-
 include/linux/jbd2.h                          |  2 +-
 include/linux/list.h                          |  2 +-
 include/linux/memblock.h                      |  4 +-
 include/linux/netdevice.h                     | 11 ++-
 include/linux/parport.h                       | 31 ++++++++
 include/linux/w1.h                            |  2 +-
 include/rdma/ib_verbs.h                       | 11 +++
 kernel/irq/chip.c                             |  2 +-
 kernel/irq/generic-chip.c                     |  2 +-
 kernel/resource.c                             | 24 ++++---
 kernel/sched/core.c                           | 16 ++---
 kernel/sched/fair.c                           |  2 +-
 kernel/time/hrtimer.c                         |  2 +-
 lib/crc7.c                                    |  2 +-
 mm/gup.c                                      | 24 ++++---
 mm/page_alloc.c                               | 16 ++---
 mm/truncate.c                                 | 10 ++-
 net/core/datagram.c                           |  2 +-
 net/core/dev.c                                |  4 +-
 net/core/skbuff.c                             |  2 +-
 net/ethernet/eth.c                            |  6 +-
 net/sunrpc/rpc_pipe.c                         |  3 +-
 scripts/kernel-doc                            | 62 +++++++++++-----
 tools/testing/selftests/kselftest_harness.h   | 22 +++---
 79 files changed, 350 insertions(+), 235 deletions(-)

-- 
2.28.0

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

[Mauro Carvalho Chehab]

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(-)

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

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

[Daniel Vetter]

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
> 

-- 
Daniel Vetter
Software Engineer, Intel Corporation
http://blog.ffwll.ch

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

[Mauro Carvalho Chehab]

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

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

[Daniel Vetter]

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

-- 
Daniel Vetter
Software Engineer, Intel Corporation
http://blog.ffwll.ch

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

[Sam Ravnborg]

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

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

[Daniel Vetter]

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
-- 
Daniel Vetter
Software Engineer, Intel Corporation
http://blog.ffwll.ch

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

[Mauro Carvalho Chehab]

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.

Re: [PATCH v4 00/27]Fix several bad kernel-doc markups

[Jakub Kicinski]

On Mon, 16 Nov 2020 11:17:56 +0100 Mauro Carvalho Chehab wrote:
> Kernel-doc has always be limited to a probably bad documented
> rule:
> 
> The kernel-doc markups should appear *imediatelly before* the
> function or data structure that it documents.

Applied 1-3 to net-next, thanks!