* [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).