[PATCH v6 00/16] Fix several bad kernel-doc markups

[PATCH v6 00/16] Fix several bad kernel-doc markups

[Mauro Carvalho Chehab]

Hi Jon,

This series have three parts:

1)  10 remaining fixup patches from the series I sent back on Dec, 1st:

   parport: fix a kernel-doc markup
   rapidio: fix kernel-doc a markup
   fs: fix kernel-doc markups
   pstore/zone: fix a kernel-doc markup
   firmware: stratix10-svc: fix kernel-doc markups
   connector: fix a kernel-doc markup
   lib/crc7: fix a kernel-doc markup
   memblock: fix kernel-doc markups
   w1: fix a kernel-doc markup
   selftests: kselftest_harness.h: partially fix kernel-doc markups

2) The patch adding the new check to ensure that the kernel-doc
   markup will be used for the right declaration;

3) 5 additional patches, produced against next-20210114 with new
   problems detected after the original series: 

 net: tip: fix a couple kernel-doc markups
 net: cfg80211: fix a kerneldoc markup
 reset: core: fix a kernel-doc markup
 drm: drm_crc: fix a kernel-doc markup
 platform/surface: aggregator: fix a kernel-doc markup

It probably makes sense to merge at least the first 11 patches
via the doc tree, as they should apply cleanly there, and
having the last 5 patches merged via each maintainer's tree.

-

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.

--

v6:
  - rebased on the top of next-20210114 and added a few extra fixes

v5:
  - The completion.h patch was replaced by another one which drops
    an obsolete macro;
  - Some typos got fixed and review tags got added;
  - Dropped patches that were already merged at linux-next.

v4:

  - Patches got rebased and got some acks.

Mauro Carvalho Chehab (16):
  parport: fix a kernel-doc markup
  rapidio: fix kernel-doc a markup
  fs: fix kernel-doc markups
  pstore/zone: fix a kernel-doc markup
  firmware: stratix10-svc: fix kernel-doc markups
  connector: fix a kernel-doc markup
  lib/crc7: fix a kernel-doc markup
  memblock: fix kernel-doc markups
  w1: fix a kernel-doc markup
  selftests: kselftest_harness.h: partially fix kernel-doc markups
  scripts: kernel-doc: validate kernel-doc markup with the actual names
  net: tip: fix a couple kernel-doc markups
  net: cfg80211: fix a kerneldoc markup
  reset: core: fix a kernel-doc markup
  drm: drm_crc: fix a kernel-doc markup
  platform/surface: aggregator: fix a kernel-doc markup

 drivers/parport/share.c                       |  2 +-
 .../surface/aggregator/ssh_request_layer.c    |  2 +-
 drivers/rapidio/rio.c                         |  2 +-
 drivers/reset/core.c                          |  4 +-
 fs/dcache.c                                   | 73 ++++++++++---------
 fs/inode.c                                    |  4 +-
 fs/pstore/zone.c                              |  2 +-
 fs/seq_file.c                                 |  5 +-
 fs/super.c                                    | 12 +--
 include/drm/drm_crtc.h                        |  2 +-
 include/linux/connector.h                     |  2 +-
 .../firmware/intel/stratix10-svc-client.h     | 10 +--
 include/linux/memblock.h                      |  4 +-
 include/linux/parport.h                       | 31 ++++++++
 include/linux/w1.h                            |  2 +-
 include/net/cfg80211.h                        |  2 +-
 lib/crc7.c                                    |  2 +-
 net/tipc/link.c                               |  2 +-
 net/tipc/node.c                               |  2 +-
 scripts/kernel-doc                            | 62 ++++++++++++----
 tools/testing/selftests/kselftest_harness.h   | 26 ++++---
 21 files changed, 160 insertions(+), 93 deletions(-)

-- 
2.29.2

[PATCH v6 12/16] net: tip: fix a couple kernel-doc markups

[Mauro Carvalho Chehab]

A function has a different name between their prototype
and its kernel-doc markup:

	../net/tipc/link.c:2551: warning: expecting prototype for link_reset_stats(). Prototype was for tipc_link_reset_stats() instead
	../net/tipc/node.c:1678: warning: expecting prototype for is the general link level function for message sending(). Prototype was for tipc_node_xmit() instead

Signed-off-by: Mauro Carvalho Chehab <mchehab+huawei@kernel.org>
---
 net/tipc/link.c | 2 +-
 net/tipc/node.c | 2 +-
 2 files changed, 2 insertions(+), 2 deletions(-)

diff --git a/net/tipc/link.c b/net/tipc/link.c
index a6a694b78927..115109259430 100644
--- a/net/tipc/link.c
+++ b/net/tipc/link.c
@@ -2544,7 +2544,7 @@ void tipc_link_set_queue_limits(struct tipc_link *l, u32 min_win, u32 max_win)
 }
 
 /**
- * link_reset_stats - reset link statistics
+ * tipc_link_reset_stats - reset link statistics
  * @l: pointer to link
  */
 void tipc_link_reset_stats(struct tipc_link *l)
diff --git a/net/tipc/node.c b/net/tipc/node.c
index 83d9eb830592..008670d1f43e 100644
--- a/net/tipc/node.c
+++ b/net/tipc/node.c
@@ -1665,7 +1665,7 @@ static void tipc_lxc_xmit(struct net *peer_net, struct sk_buff_head *list)
 }
 
 /**
- * tipc_node_xmit() is the general link level function for message sending
+ * tipc_node_xmit() - general link level function for message sending
  * @net: the applicable net namespace
  * @list: chain of buffers containing message
  * @dnode: address of destination node
-- 
2.29.2

[PATCH v6 13/16] net: cfg80211: fix a kerneldoc markup

[Mauro Carvalho Chehab]

A function has a different name between their prototype
and its kernel-doc markup:
	../include/net/cfg80211.h:1766: warning: expecting prototype for struct cfg80211_sar_chan_ranges. Prototype was for struct cfg80211_sar_freq_ranges instead

Signed-off-by: Mauro Carvalho Chehab <mchehab+huawei@kernel.org>
---
 include/net/cfg80211.h | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/include/net/cfg80211.h b/include/net/cfg80211.h
index 1b3954afcda4..0d6f7ec86061 100644
--- a/include/net/cfg80211.h
+++ b/include/net/cfg80211.h
@@ -1756,7 +1756,7 @@ struct cfg80211_sar_specs {
 
 
 /**
- * struct cfg80211_sar_chan_ranges - sar frequency ranges
+ * struct cfg80211_sar_freq_ranges - sar frequency ranges
  * @start_freq:  start range edge frequency
  * @end_freq:    end range edge frequency
  */
-- 
2.29.2

Re: [PATCH v6 12/16] net: tip: fix a couple kernel-doc markups

[Jon Maloy]

On 1/14/21 3:04 AM, Mauro Carvalho Chehab wrote:
> A function has a different name between their prototype
> and its kernel-doc markup:
>
> 	../net/tipc/link.c:2551: warning: expecting prototype for link_reset_stats(). Prototype was for tipc_link_reset_stats() instead
> 	../net/tipc/node.c:1678: warning: expecting prototype for is the general link level function for message sending(). Prototype was for tipc_node_xmit() instead
>
> Signed-off-by: Mauro Carvalho Chehab <mchehab+huawei@kernel.org>
> ---
>   net/tipc/link.c | 2 +-
>   net/tipc/node.c | 2 +-
>   2 files changed, 2 insertions(+), 2 deletions(-)
>
> diff --git a/net/tipc/link.c b/net/tipc/link.c
> index a6a694b78927..115109259430 100644
> --- a/net/tipc/link.c
> +++ b/net/tipc/link.c
> @@ -2544,7 +2544,7 @@ void tipc_link_set_queue_limits(struct tipc_link *l, u32 min_win, u32 max_win)
>   }
>   
>   /**
> - * link_reset_stats - reset link statistics
> + * tipc_link_reset_stats - reset link statistics
>    * @l: pointer to link
>    */
>   void tipc_link_reset_stats(struct tipc_link *l)
> diff --git a/net/tipc/node.c b/net/tipc/node.c
> index 83d9eb830592..008670d1f43e 100644
> --- a/net/tipc/node.c
> +++ b/net/tipc/node.c
> @@ -1665,7 +1665,7 @@ static void tipc_lxc_xmit(struct net *peer_net, struct sk_buff_head *list)
>   }
>   
>   /**
> - * tipc_node_xmit() is the general link level function for message sending
> + * tipc_node_xmit() - general link level function for message sending
>    * @net: the applicable net namespace
>    * @list: chain of buffers containing message
>    * @dnode: address of destination node
Acked-by: Jon Maloy <jmaloy@redhat.com>

Re: [PATCH v6 12/16] net: tip: fix a couple kernel-doc markups

[Jakub Kicinski]

On Thu, 14 Jan 2021 10:59:08 -0500 Jon Maloy wrote:
> On 1/14/21 3:04 AM, Mauro Carvalho Chehab wrote:
> > A function has a different name between their prototype
> > and its kernel-doc markup:
> >
> > 	../net/tipc/link.c:2551: warning: expecting prototype for link_reset_stats(). Prototype was for tipc_link_reset_stats() instead
> > 	../net/tipc/node.c:1678: warning: expecting prototype for is the general link level function for message sending(). Prototype was for tipc_node_xmit() instead
> >
> > Signed-off-by: Mauro Carvalho Chehab <mchehab+huawei@kernel.org>
> 
> Acked-by: Jon Maloy <jmaloy@redhat.com>

Thanks! Applied this one to net, the cfg80211 one does not apply to
net, so I'll leave it to Johannes.

Re: [PATCH v6 12/16] net: tip: fix a couple kernel-doc markups

[Johannes Berg]

On Thu, 2021-01-14 at 10:34 -0800, Jakub Kicinski wrote:
> On Thu, 14 Jan 2021 10:59:08 -0500 Jon Maloy wrote:
> > On 1/14/21 3:04 AM, Mauro Carvalho Chehab wrote:
> > > A function has a different name between their prototype
> > > and its kernel-doc markup:
> > > 
> > > 	../net/tipc/link.c:2551: warning: expecting prototype for link_reset_stats(). Prototype was for tipc_link_reset_stats() instead
> > > 	../net/tipc/node.c:1678: warning: expecting prototype for is the general link level function for message sending(). Prototype was for tipc_node_xmit() instead
> > > 
> > > Signed-off-by: Mauro Carvalho Chehab <mchehab+huawei@kernel.org>
> > 
> > Acked-by: Jon Maloy <jmaloy@redhat.com>
> 
> Thanks! Applied this one to net, the cfg80211 one does not apply to
> net, so I'll leave it to Johannes.

Right, that was diffed against -next, and I've got a fix pending that I
didn't send yet.

I've applied this now, thanks.

johannes

Re: [PATCH v6 00/16] Fix several bad kernel-doc markups

[Jonathan Corbet]

On Thu, 14 Jan 2021 09:04:36 +0100
Mauro Carvalho Chehab <mchehab+huawei@kernel.org> wrote:

> 1)  10 remaining fixup patches from the series I sent back on Dec, 1st:
> 
>    parport: fix a kernel-doc markup
>    rapidio: fix kernel-doc a markup
>    fs: fix kernel-doc markups
>    pstore/zone: fix a kernel-doc markup
>    firmware: stratix10-svc: fix kernel-doc markups
>    connector: fix a kernel-doc markup
>    lib/crc7: fix a kernel-doc markup
>    memblock: fix kernel-doc markups
>    w1: fix a kernel-doc markup
>    selftests: kselftest_harness.h: partially fix kernel-doc markups

A week later none of these have shown up in linux-next, so I went ahead
and applied the set.

Thanks,

jon