linux-wireless.vger.kernel.org archive mirror
 help / color / mirror / 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 13/16] net: cfg80211: fix a kerneldoc markup Mauro Carvalho Chehab
  2021-01-21 19:09 ` [PATCH v6 00/16] Fix several bad kernel-doc markups Jonathan Corbet
  0 siblings, 2 replies; 3+ 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] 3+ 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 ` Mauro Carvalho Chehab
  2021-01-21 19:09 ` [PATCH v6 00/16] Fix several bad kernel-doc markups Jonathan Corbet
  1 sibling, 0 replies; 3+ 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 related	[flat|nested] 3+ messages in thread

* Re: [PATCH v6 00/16] Fix several bad 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 ` [PATCH v6 13/16] net: cfg80211: fix a kerneldoc markup Mauro Carvalho Chehab
@ 2021-01-21 19:09 ` Jonathan Corbet
  1 sibling, 0 replies; 3+ messages in thread
From: Jonathan Corbet @ 2021-01-21 19:09 UTC (permalink / raw)
  To: Mauro Carvalho Chehab
  Cc: Linux Doc Mailing List, 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

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

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

end of thread, other threads:[~2021-01-21 19:12 UTC | newest]

Thread overview: 3+ 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 13/16] net: cfg80211: fix a kerneldoc markup Mauro Carvalho Chehab
2021-01-21 19:09 ` [PATCH v6 00/16] Fix several bad kernel-doc markups Jonathan Corbet

This is a public inbox, see mirroring instructions
for how to clone and mirror all data and code used for this inbox;
as well as URLs for NNTP newsgroup(s).