Netdev Archive on lore.kernel.org
 help / color / Atom feed
* [PATCH v6 00/16] Fix several bad kernel-doc markups
@ 2021-01-14  8:04 Mauro Carvalho Chehab
  2021-01-14  8:04 ` [PATCH v6 12/16] net: tip: fix a couple " Mauro Carvalho Chehab
  2021-01-14  8:04 ` [PATCH v6 13/16] net: cfg80211: fix a kerneldoc markup Mauro Carvalho Chehab
  0 siblings, 2 replies; 6+ messages in thread
From: Mauro Carvalho Chehab @ 2021-01-14  8:04 UTC (permalink / raw)
  To: Linux Doc Mailing List, Jonathan Corbet
  Cc: Mauro Carvalho Chehab, linux-kernel, David S. Miller,
	Alexander Viro, Alexandre Bounine, Andy Lutomirski,
	Anton Vorontsov, Colin Cross, Daniel Vetter, David Airlie,
	Evgeniy Polyakov, Hans de Goede, Jakub Kicinski, Johannes Berg,
	Jon Maloy, Kees Cook, Maarten Lankhorst, Mark Gross, Matt Porter,
	Maxime Ripard, Maximilian Luz, Mike Rapoport, Philipp Zabel,
	Richard Gong, Shuah Khan, Sudip Mukherjee, Thomas Zimmermann,
	Tony Luck, Will Drewry, Ying Xue, dri-devel, linux-fsdevel,
	linux-kselftest, linux-mm, linux-wireless, netdev,
	platform-driver-x86, tipc-discussion

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



^ permalink raw reply	[flat|nested] 6+ messages in thread

* [PATCH v6 12/16] net: tip: fix a couple kernel-doc markups
  2021-01-14  8:04 [PATCH v6 00/16] Fix several bad kernel-doc markups Mauro Carvalho Chehab
@ 2021-01-14  8:04 ` Mauro Carvalho Chehab
  2021-01-14 15:59   ` Jon Maloy
  2021-01-14  8:04 ` [PATCH v6 13/16] net: cfg80211: fix a kerneldoc markup Mauro Carvalho Chehab
  1 sibling, 1 reply; 6+ messages in thread
From: Mauro Carvalho Chehab @ 2021-01-14  8:04 UTC (permalink / raw)
  To: Linux Doc Mailing List, Jonathan Corbet
  Cc: Mauro Carvalho Chehab, David S. Miller, Jakub Kicinski,
	Jon Maloy, Ying Xue, linux-kernel, netdev, tipc-discussion

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


^ permalink raw reply	[flat|nested] 6+ messages in thread

* [PATCH v6 13/16] net: cfg80211: fix a kerneldoc markup
  2021-01-14  8:04 [PATCH v6 00/16] Fix several bad kernel-doc markups Mauro Carvalho Chehab
  2021-01-14  8:04 ` [PATCH v6 12/16] net: tip: fix a couple " Mauro Carvalho Chehab
@ 2021-01-14  8:04 ` Mauro Carvalho Chehab
  1 sibling, 0 replies; 6+ messages in thread
From: Mauro Carvalho Chehab @ 2021-01-14  8:04 UTC (permalink / raw)
  To: Linux Doc Mailing List, Jonathan Corbet
  Cc: Mauro Carvalho Chehab, David S. Miller, Jakub Kicinski,
	Johannes Berg, linux-kernel, linux-wireless, netdev

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


^ permalink raw reply	[flat|nested] 6+ messages in thread

* Re: [PATCH v6 12/16] net: tip: fix a couple kernel-doc markups
  2021-01-14  8:04 ` [PATCH v6 12/16] net: tip: fix a couple " Mauro Carvalho Chehab
@ 2021-01-14 15:59   ` Jon Maloy
  2021-01-14 18:34     ` Jakub Kicinski
  0 siblings, 1 reply; 6+ messages in thread
From: Jon Maloy @ 2021-01-14 15:59 UTC (permalink / raw)
  To: Mauro Carvalho Chehab, Linux Doc Mailing List, Jonathan Corbet
  Cc: David S. Miller, Jakub Kicinski, Ying Xue, linux-kernel, netdev,
	tipc-discussion



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>


^ permalink raw reply	[flat|nested] 6+ messages in thread

* Re: [PATCH v6 12/16] net: tip: fix a couple kernel-doc markups
  2021-01-14 15:59   ` Jon Maloy
@ 2021-01-14 18:34     ` Jakub Kicinski
  2021-01-14 21:22       ` Johannes Berg
  0 siblings, 1 reply; 6+ messages in thread
From: Jakub Kicinski @ 2021-01-14 18:34 UTC (permalink / raw)
  To: Jon Maloy, Mauro Carvalho Chehab, Johannes Berg
  Cc: Linux Doc Mailing List, Jonathan Corbet, David S. Miller,
	Ying Xue, linux-kernel, netdev, tipc-discussion

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.

^ permalink raw reply	[flat|nested] 6+ messages in thread

* Re: [PATCH v6 12/16] net: tip: fix a couple kernel-doc markups
  2021-01-14 18:34     ` Jakub Kicinski
@ 2021-01-14 21:22       ` Johannes Berg
  0 siblings, 0 replies; 6+ messages in thread
From: Johannes Berg @ 2021-01-14 21:22 UTC (permalink / raw)
  To: Jakub Kicinski, Jon Maloy, Mauro Carvalho Chehab
  Cc: Linux Doc Mailing List, Jonathan Corbet, David S. Miller,
	Ying Xue, linux-kernel, netdev, tipc-discussion

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


^ permalink raw reply	[flat|nested] 6+ messages in thread

end of thread, back to index

Thread overview: 6+ messages (download: mbox.gz / follow: Atom feed)
-- links below jump to the message on this page --
2021-01-14  8:04 [PATCH v6 00/16] Fix several bad kernel-doc markups Mauro Carvalho Chehab
2021-01-14  8:04 ` [PATCH v6 12/16] net: tip: fix a couple " Mauro Carvalho Chehab
2021-01-14 15:59   ` Jon Maloy
2021-01-14 18:34     ` Jakub Kicinski
2021-01-14 21:22       ` Johannes Berg
2021-01-14  8:04 ` [PATCH v6 13/16] net: cfg80211: fix a kerneldoc markup Mauro Carvalho Chehab

Netdev Archive on lore.kernel.org

Archives are clonable:
	git clone --mirror https://lore.kernel.org/netdev/0 netdev/git/0.git
	git clone --mirror https://lore.kernel.org/netdev/1 netdev/git/1.git

	# If you have public-inbox 1.1+ installed, you may
	# initialize and index your mirror using the following commands:
	public-inbox-init -V2 netdev netdev/ https://lore.kernel.org/netdev \
		netdev@vger.kernel.org
	public-inbox-index netdev

Example config snippet for mirrors

Newsgroup available over NNTP:
	nntp://nntp.lore.kernel.org/org.kernel.vger.netdev


AGPL code for this site: git clone https://public-inbox.org/public-inbox.git