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
Probaly this was due to a cut and paste issue.
Signed-off-by: Mauro Carvalho Chehab <mchehab+huawei@kernel.org>
---
drivers/rapidio/rio.c | 2 +-
1 file changed, 1 insertion(+), 1 deletion(-)
A function has a different name between their prototype
and its kernel-doc markup.
Signed-off-by: Mauro Carvalho Chehab <mchehab+huawei@kernel.org>
---
include/linux/connector.h | 2 +-
1 file changed, 1 insertion(+), 1 deletion(-)
There are some common comments marked, instead, with kernel-doc
notation, which won't work.
While here, rename an identifier, in order to match the
function prototype below kernel-doc markup.
Acked-by: Richard Gong <redacted>
Signed-off-by: Mauro Carvalho Chehab <mchehab+huawei@kernel.org>
---
include/linux/firmware/intel/stratix10-svc-client.h | 10 +++++-----
1 file changed, 5 insertions(+), 5 deletions(-)
Two markups are at the wrong place. Kernel-doc only
support having the comment just before the identifier.
Also, some identifiers have different names between their
prototypes and the kernel-doc markup.
Signed-off-by: Mauro Carvalho Chehab <mchehab+huawei@kernel.org>
---
fs/dcache.c | 73 ++++++++++++++++++++++++++-------------------------
fs/inode.c | 4 +--
fs/seq_file.c | 5 ++--
fs/super.c | 12 ++++-----
4 files changed, 48 insertions(+), 46 deletions(-)
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(-)
A function has a different name between their prototype
and its kernel-doc markup.
Signed-off-by: Mauro Carvalho Chehab <mchehab+huawei@kernel.org>
---
include/linux/w1.h | 2 +-
1 file changed, 1 insertion(+), 1 deletion(-)
The kernel-doc markup inside share.c is actually for
__parport_register_driver. The actual goal seems to be
to document parport_register_driver().
So, fix the existing markup and add a new one.
Signed-off-by: Mauro Carvalho Chehab <mchehab+huawei@kernel.org>
---
drivers/parport/share.c | 2 +-
include/linux/parport.h | 31 +++++++++++++++++++++++++++++++
2 files changed, 32 insertions(+), 1 deletion(-)
The kernel-doc markups on this file are weird: they don't
follow what's specified at:
Documentation/doc-guide/kernel-doc.rst
In particular, markups should use this format:
identifier - description
and not this:
identifier(args)
The way the definitions are inside this file cause the
parser to completely miss the identifier name of each
function.
This prevents improving the script to do some needed validation
tests.
Address this part. Yet, furter changes are needed in order
for it to fully follow the specs.
Acked-by: Kees Cook <redacted>
Signed-off-by: Mauro Carvalho Chehab <mchehab+huawei@kernel.org>
---
tools/testing/selftests/kselftest_harness.h | 26 ++++++++++++---------
1 file changed, 15 insertions(+), 11 deletions(-)
Kernel-doc currently expects that the kernel-doc markup to come
just before the function/enum/struct/union/typedef prototype.
Yet, if it find things like:
/**
* refcount_add - add a value to a refcount
* @i: the value to add to the refcount
* @r: the refcount
*/
static inline void __refcount_add(int i, refcount_t *r, int *oldp);
static inline void refcount_add(int i, refcount_t *r);
Kernel-doc will do the wrong thing:
foobar.h:6: warning: Function parameter or member 'oldp' not described in '__refcount_add'
.. c:function:: void __refcount_add (int i, refcount_t *r, int *oldp)
add a value to a refcount
**Parameters**
``int i``
the value to add to the refcount
``refcount_t *r``
the refcount
``int *oldp``
*undescribed*
Basically, it will document "__refcount_add" with the kernel-doc
markup for refcount_add.
If both functions have the same arguments, this won't even
produce any warning!
Add a logic to check if the kernel-doc identifier matches the actual
name of the C function or data structure that will be documented.
Signed-off-by: Mauro Carvalho Chehab <mchehab+huawei@kernel.org>
---
scripts/kernel-doc | 62 ++++++++++++++++++++++++++++++++++------------
1 file changed, 46 insertions(+), 16 deletions(-)
@@ -382,6 +382,9 @@ my $inline_doc_state; # 'function', 'struct', 'union', 'enum', 'typedef' my $decl_type;+# Name of the kernel-doc identifier for non-DOC markups+my $identifier;+ my $doc_start = '^/\*\*\s*$'; # Allow whitespace at end of comment start. my $doc_end = '\*/'; my $doc_com = '\s*\*\s*';
@@ -1203,6 +1206,11 @@ sub dump_struct($$) { $declaration_name = $2; my $members = $3;+ if ($identifier ne $declaration_name) {+ print STDERR "${file}:$.: warning: expecting prototype for $decl_type $identifier. Prototype was for $decl_type $declaration_name instead\n";+ return;+ }+ # ignore members marked private: $members =~ s/\/\*\s*private:.*?\/\*\s*public:.*?\*\///gosi; $members =~ s/\/\*\s*private:.*//gosi;
@@ -1391,6 +1399,11 @@ sub dump_enum($$) { } if ($members) {+ if ($identifier ne $declaration_name) {+ print STDERR "${file}:$.: warning: expecting prototype for enum $identifier. Prototype was for enum $declaration_name instead\n";+ return;+ }+ my %_members; $members =~ s/\s+$//;
@@ -1451,6 +1464,11 @@ sub dump_typedef($$) { my $args = $3; $return_type =~ s/^\s+//;+ if ($identifier ne $declaration_name) {+ print STDERR "${file}:$.: warning: expecting prototype for typedef $identifier. Prototype was for typedef $declaration_name instead\n";+ return;+ }+ create_parameterlist($args, ',', $file, $declaration_name); output_declaration($declaration_name,
@@ -1477,6 +1495,11 @@ sub dump_typedef($$) { if ($x =~ /typedef.*\s+(\w+)\s*;/) { $declaration_name = $1;+ if ($identifier ne $declaration_name) {+ print STDERR "${file}:$.: warning: expecting prototype for typedef $identifier. Prototype was for typedef $declaration_name instead\n";+ return;+ }+ output_declaration($declaration_name, 'typedef', {'typedef' => $declaration_name,
@@ -1796,6 +1819,11 @@ sub dump_function($$) { return; }+ if ($identifier ne $declaration_name) {+ print STDERR "${file}:$.: warning: expecting prototype for $identifier(). Prototype was for $declaration_name() instead\n";+ return;+ }+ my $prms = join " ", @parameterlist; check_sections($file, $declaration_name, "function", $sectcheck, $prms);
From: kernel test robot <hidden> Date: 2021-01-14 10:13:13
Hi Mauro,
I love your patch! Perhaps something to improve:
[auto build test WARNING on next-20210113]
[also build test WARNING on v5.11-rc3]
[cannot apply to lwn/docs-next kees/for-next/pstore mac80211-next/master mac80211/master pza/reset/next linus/master v5.11-rc3 v5.11-rc2 v5.11-rc1]
[If your patch is applied to the wrong git tree, kindly drop us a note.
And when submitting patch, we suggest to use '--base' as documented in
https://git-scm.com/docs/git-format-patch]
url: https://github.com/0day-ci/linux/commits/Mauro-Carvalho-Chehab/Fix-several-bad-kernel-doc-markups/20210114-161010
base: aa515cdce7a151dcc14b7600d33f1414c6fa32c9
config: arm64-alldefconfig (attached as .config)
compiler: aarch64-linux-gcc (GCC) 9.3.0
reproduce (this is a W=1 build):
wget https://raw.githubusercontent.com/intel/lkp-tests/master/sbin/make.cross -O ~/bin/make.cross
chmod +x ~/bin/make.cross
# https://github.com/0day-ci/linux/commit/1e9159b3640012fc5fab8508b1c5635ac13a55e9
git remote add linux-review https://github.com/0day-ci/linux
git fetch --no-tags linux-review Mauro-Carvalho-Chehab/Fix-several-bad-kernel-doc-markups/20210114-161010
git checkout 1e9159b3640012fc5fab8508b1c5635ac13a55e9
# save the attached .config to linux build tree
COMPILER_INSTALL_PATH=$HOME/0day COMPILER=gcc-9.3.0 make.cross ARCH=arm64
If you fix the issue, kindly add following tag as appropriate
Reported-by: kernel test robot <redacted>
All warnings (new ones prefixed by >>):
kernel/seccomp.c:126: warning: Function parameter or member 'list' not described in 'seccomp_kaddfd'
kernel/seccomp.c:390: warning: Function parameter or member 'ret' not described in 'ACTION_ONLY'
quoted
kernel/seccomp.c:390: warning: expecting prototype for seccomp_run_filters(). Prototype was for ACTION_ONLY() instead
kernel/seccomp.c:553: warning: Function parameter or member 'tsk' not described in 'seccomp_filter_release'
kernel/seccomp.c:573: warning: Function parameter or member 'flags' not described in 'seccomp_sync_threads'
--
drivers/base/platform-msi.c:336: warning: Function parameter or member 'is_tree' not described in '__platform_msi_create_device_domain'
quoted
drivers/base/platform-msi.c:336: warning: expecting prototype for platform_msi_create_device_domain(). Prototype was for __platform_msi_create_device_domain() instead
--
quoted
drivers/iommu/iommu.c:956: warning: expecting prototype for iommu_group_for_each_dev(). Prototype was for __iommu_group_for_each_dev() instead
drivers/iommu/iommu.c:2976: warning: Function parameter or member 'drvdata' not described in 'iommu_sva_bind_device'
--
quoted
kernel/irq/msi.c:534: warning: expecting prototype for __msi_domain_free_irqs(). Prototype was for msi_domain_free_irqs() instead
--
quoted
kernel/irq/ipi.c:264: warning: expecting prototype for ipi_send_mask(). Prototype was for __ipi_send_mask() instead
vim +390 kernel/seccomp.c
f9d480b6ffbeb336 YiFei Zhu 2020-10-11 380
e2cfabdfd0756482 Will Drewry 2012-04-12 381 /**
285fdfc5d9959a21 Mickaël Salaün 2016-09-20 382 * seccomp_run_filters - evaluates all seccomp filters against @sd
285fdfc5d9959a21 Mickaël Salaün 2016-09-20 383 * @sd: optional seccomp data to be passed to filters
deb4de8b31bc5bf2 Kees Cook 2017-08-02 384 * @match: stores struct seccomp_filter that resulted in the return value,
deb4de8b31bc5bf2 Kees Cook 2017-08-02 385 * unless filter returned SECCOMP_RET_ALLOW, in which case it will
deb4de8b31bc5bf2 Kees Cook 2017-08-02 386 * be unchanged.
e2cfabdfd0756482 Will Drewry 2012-04-12 387 *
e2cfabdfd0756482 Will Drewry 2012-04-12 388 * Returns valid seccomp BPF response codes.
e2cfabdfd0756482 Will Drewry 2012-04-12 389 */
0466bdb99e8744bc Kees Cook 2017-08-11 @390 #define ACTION_ONLY(ret) ((s32)((ret) & (SECCOMP_RET_ACTION_FULL)))
deb4de8b31bc5bf2 Kees Cook 2017-08-02 391 static u32 seccomp_run_filters(const struct seccomp_data *sd,
deb4de8b31bc5bf2 Kees Cook 2017-08-02 392 struct seccomp_filter **match)
e2cfabdfd0756482 Will Drewry 2012-04-12 393 {
acf3b2c71ed20c53 Will Drewry 2012-04-12 394 u32 ret = SECCOMP_RET_ALLOW;
8225d3853f34f6cf Pranith Kumar 2014-11-21 395 /* Make sure cross-thread synced filter points somewhere sane. */
8225d3853f34f6cf Pranith Kumar 2014-11-21 396 struct seccomp_filter *f =
506458efaf153c1e Will Deacon 2017-10-24 397 READ_ONCE(current->seccomp.filter);
acf3b2c71ed20c53 Will Drewry 2012-04-12 398
acf3b2c71ed20c53 Will Drewry 2012-04-12 399 /* Ensure unexpected behavior doesn't result in failing open. */
0d42d73a37ff9102 Igor Stoppa 2018-09-05 400 if (WARN_ON(f == NULL))
4d3b0b05aae9ee9c Kees Cook 2017-08-11 401 return SECCOMP_RET_KILL_PROCESS;
acf3b2c71ed20c53 Will Drewry 2012-04-12 402
f9d480b6ffbeb336 YiFei Zhu 2020-10-11 403 if (seccomp_cache_check_allow(f, sd))
f9d480b6ffbeb336 YiFei Zhu 2020-10-11 404 return SECCOMP_RET_ALLOW;
f9d480b6ffbeb336 YiFei Zhu 2020-10-11 405
e2cfabdfd0756482 Will Drewry 2012-04-12 406 /*
e2cfabdfd0756482 Will Drewry 2012-04-12 407 * All filters in the list are evaluated and the lowest BPF return
acf3b2c71ed20c53 Will Drewry 2012-04-12 408 * value always takes priority (ignoring the DATA).
e2cfabdfd0756482 Will Drewry 2012-04-12 409 */
3ba2530cc06eb4ae Kees Cook 2014-06-27 410 for (; f; f = f->prev) {
3d9f773cf2876c01 David Miller 2020-02-24 411 u32 cur_ret = bpf_prog_run_pin_on_cpu(f->prog, sd);
8f577cadf7181243 Alexei Starovoitov 2014-05-13 412
0466bdb99e8744bc Kees Cook 2017-08-11 413 if (ACTION_ONLY(cur_ret) < ACTION_ONLY(ret)) {
acf3b2c71ed20c53 Will Drewry 2012-04-12 414 ret = cur_ret;
deb4de8b31bc5bf2 Kees Cook 2017-08-02 415 *match = f;
deb4de8b31bc5bf2 Kees Cook 2017-08-02 416 }
e2cfabdfd0756482 Will Drewry 2012-04-12 417 }
e2cfabdfd0756482 Will Drewry 2012-04-12 418 return ret;
e2cfabdfd0756482 Will Drewry 2012-04-12 419 }
1f41b450416e689b Kees Cook 2014-06-25 420 #endif /* CONFIG_SECCOMP_FILTER */
1f41b450416e689b Kees Cook 2014-06-25 421
---
0-DAY CI Kernel Test Service, Intel Corporation
https://lists.01.org/hyperkitty/list/kbuild-all@lists.01.org
From: kernel test robot <hidden> Date: 2021-01-14 10:17:59
Hi Mauro,
I love your patch! Perhaps something to improve:
[auto build test WARNING on next-20210113]
[also build test WARNING on v5.11-rc3]
[cannot apply to lwn/docs-next kees/for-next/pstore mac80211-next/master mac80211/master pza/reset/next linus/master v5.11-rc3 v5.11-rc2 v5.11-rc1]
[If your patch is applied to the wrong git tree, kindly drop us a note.
And when submitting patch, we suggest to use '--base' as documented in
https://git-scm.com/docs/git-format-patch]
url: https://github.com/0day-ci/linux/commits/Mauro-Carvalho-Chehab/Fix-several-bad-kernel-doc-markups/20210114-161010
base: aa515cdce7a151dcc14b7600d33f1414c6fa32c9
config: mips-nlm_xlp_defconfig (attached as .config)
compiler: mips64-linux-gcc (GCC) 9.3.0
reproduce (this is a W=1 build):
wget https://raw.githubusercontent.com/intel/lkp-tests/master/sbin/make.cross -O ~/bin/make.cross
chmod +x ~/bin/make.cross
# https://github.com/0day-ci/linux/commit/1e9159b3640012fc5fab8508b1c5635ac13a55e9
git remote add linux-review https://github.com/0day-ci/linux
git fetch --no-tags linux-review Mauro-Carvalho-Chehab/Fix-several-bad-kernel-doc-markups/20210114-161010
git checkout 1e9159b3640012fc5fab8508b1c5635ac13a55e9
# save the attached .config to linux build tree
COMPILER_INSTALL_PATH=$HOME/0day COMPILER=gcc-9.3.0 make.cross ARCH=mips
If you fix the issue, kindly add following tag as appropriate
Reported-by: kernel test robot <redacted>
All warnings (new ones prefixed by >>):
arch/mips/kernel/module.c:289: warning: Function parameter or member 'reloc_handler' not described in 'int'
quoted
arch/mips/kernel/module.c:289: warning: expecting prototype for reloc_handler(). Prototype was for int() instead
--
arch/mips/kernel/kprobes.c:196: warning: Function parameter or member 'p' not described in 'evaluate_branch_instruction'
arch/mips/kernel/kprobes.c:196: warning: Function parameter or member 'regs' not described in 'evaluate_branch_instruction'
arch/mips/kernel/kprobes.c:196: warning: Function parameter or member 'kcb' not described in 'evaluate_branch_instruction'
quoted
arch/mips/kernel/kprobes.c:196: warning: expecting prototype for evaluate_branch_instrucion(). Prototype was for evaluate_branch_instruction() instead
vim +289 arch/mips/kernel/module.c
5d3c792583b60406 Paul Burton 2016-02-04 272
430d0b88943afffd Paul Burton 2017-03-30 273 /**
430d0b88943afffd Paul Burton 2017-03-30 274 * reloc_handler() - Apply a particular relocation to a module
430d0b88943afffd Paul Burton 2017-03-30 275 * @me: the module to apply the reloc to
430d0b88943afffd Paul Burton 2017-03-30 276 * @location: the address at which the reloc is to be applied
430d0b88943afffd Paul Burton 2017-03-30 277 * @base: the existing value at location for REL-style; 0 for RELA-style
430d0b88943afffd Paul Burton 2017-03-30 278 * @v: the value of the reloc, with addend for RELA-style
430d0b88943afffd Paul Burton 2017-03-30 279 *
430d0b88943afffd Paul Burton 2017-03-30 280 * Each implemented reloc_handler function applies a particular type of
430d0b88943afffd Paul Burton 2017-03-30 281 * relocation to the module @me. Relocs that may be found in either REL or RELA
430d0b88943afffd Paul Burton 2017-03-30 282 * variants can be handled by making use of the @base & @v parameters which are
430d0b88943afffd Paul Burton 2017-03-30 283 * set to values which abstract the difference away from the particular reloc
430d0b88943afffd Paul Burton 2017-03-30 284 * implementations.
430d0b88943afffd Paul Burton 2017-03-30 285 *
430d0b88943afffd Paul Burton 2017-03-30 286 * Return: 0 upon success, else -ERRNO
430d0b88943afffd Paul Burton 2017-03-30 287 */
430d0b88943afffd Paul Burton 2017-03-30 288 typedef int (*reloc_handler)(struct module *me, u32 *location,
430d0b88943afffd Paul Burton 2017-03-30 @289 u32 base, Elf_Addr v, bool rela);
430d0b88943afffd Paul Burton 2017-03-30 290
---
0-DAY CI Kernel Test Service, Intel Corporation
https://lists.01.org/hyperkitty/list/kbuild-all@lists.01.org
From: Jonathan Corbet <corbet@lwn.net> Date: 2021-01-18 20:37:35
On Thu, 14 Jan 2021 09:04:47 +0100
Mauro Carvalho Chehab [off-list ref] wrote:
Kernel-doc currently expects that the kernel-doc markup to come
just before the function/enum/struct/union/typedef prototype.
Yet, if it find things like:
/**
* refcount_add - add a value to a refcount
* @i: the value to add to the refcount
* @r: the refcount
*/
static inline void __refcount_add(int i, refcount_t *r, int *oldp);
static inline void refcount_add(int i, refcount_t *r);
Kernel-doc will do the wrong thing:
foobar.h:6: warning: Function parameter or member 'oldp' not described in '__refcount_add'
.. c:function:: void __refcount_add (int i, refcount_t *r, int *oldp)
add a value to a refcount
**Parameters**
``int i``
the value to add to the refcount
``refcount_t *r``
the refcount
``int *oldp``
*undescribed*
Basically, it will document "__refcount_add" with the kernel-doc
markup for refcount_add.
If both functions have the same arguments, this won't even
produce any warning!
Add a logic to check if the kernel-doc identifier matches the actual
name of the C function or data structure that will be documented.
Signed-off-by: Mauro Carvalho Chehab <mchehab+huawei@kernel.org>
I've applied this one; it seems useful to have even if it creates more
warnings that Stephen will duly email me about tomorrow...:) I have parts
1-10 set aside and will apply any that don't get picked up directly by the
maintainers involved.
Thanks,
jon
Em Mon, 18 Jan 2021 13:35:45 -0700
Jonathan Corbet [off-list ref] escreveu:
On Thu, 14 Jan 2021 09:04:47 +0100
Mauro Carvalho Chehab [off-list ref] wrote:
quoted
Kernel-doc currently expects that the kernel-doc markup to come
just before the function/enum/struct/union/typedef prototype.
Yet, if it find things like:
/**
* refcount_add - add a value to a refcount
* @i: the value to add to the refcount
* @r: the refcount
*/
static inline void __refcount_add(int i, refcount_t *r, int *oldp);
static inline void refcount_add(int i, refcount_t *r);
Kernel-doc will do the wrong thing:
foobar.h:6: warning: Function parameter or member 'oldp' not described in '__refcount_add'
.. c:function:: void __refcount_add (int i, refcount_t *r, int *oldp)
add a value to a refcount
**Parameters**
``int i``
the value to add to the refcount
``refcount_t *r``
the refcount
``int *oldp``
*undescribed*
Basically, it will document "__refcount_add" with the kernel-doc
markup for refcount_add.
If both functions have the same arguments, this won't even
produce any warning!
Add a logic to check if the kernel-doc identifier matches the actual
name of the C function or data structure that will be documented.
Signed-off-by: Mauro Carvalho Chehab <mchehab+huawei@kernel.org>
I've applied this one;
Thanks!
it seems useful to have even if it creates more
warnings that Stephen will duly email me about tomorrow...:) I have parts
1-10 set aside and will apply any that don't get picked up directly by the
maintainers involved.
Yeah, new warnings are unavoidable, as new patches may be introducing
extra issues. Hopefully, the new warning will help people to detect
the issue earlier before submitting upstream.
Thanks,
Mauro
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(-)
From: Jon Maloy <jmaloy@redhat.com> Date: 2021-01-14 16:01:03
On 1/14/21 3:04 AM, Mauro Carvalho Chehab wrote:
quoted hunk
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(-)
From: Jakub Kicinski <kuba@kernel.org> Date: 2021-01-14 18:34:46
On Thu, 14 Jan 2021 10:59:08 -0500 Jon Maloy wrote:
On 1/14/21 3:04 AM, Mauro Carvalho Chehab wrote:
quoted
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.
From: Johannes Berg <johannes@sipsolutions.net> Date: 2021-01-14 21:24:27
On Thu, 2021-01-14 at 10:34 -0800, Jakub Kicinski wrote:
On Thu, 14 Jan 2021 10:59:08 -0500 Jon Maloy wrote:
quoted
On 1/14/21 3:04 AM, Mauro Carvalho Chehab wrote:
quoted
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
A function has a different name between their prototype
and its kernel-doc markup:
../drivers/reset/core.c:888: warning: expecting prototype for device_reset(). Prototype was for __device_reset() instead
Signed-off-by: Mauro Carvalho Chehab <mchehab+huawei@kernel.org>
---
drivers/reset/core.c | 4 ++--
1 file changed, 2 insertions(+), 2 deletions(-)
From: Philipp Zabel <p.zabel@pengutronix.de> Date: 2021-01-14 08:26:53
Hi Mauro,
On Thu, 2021-01-14 at 09:04 +0100, Mauro Carvalho Chehab wrote:
quoted hunk
A function has a different name between their prototype
and its kernel-doc markup:
../drivers/reset/core.c:888: warning: expecting prototype for device_reset(). Prototype was for __device_reset() instead
Signed-off-by: Mauro Carvalho Chehab <mchehab+huawei@kernel.org>
---
drivers/reset/core.c | 4 ++--
1 file changed, 2 insertions(+), 2 deletions(-)
A function has a different name between their prototype
and its kernel-doc markup:
../drivers/platform/surface/aggregator/ssh_request_layer.c:1065: warning: expecting prototype for ssh_rtl_tx_start(). Prototype was for ssh_rtl_start() instead
Signed-off-by: Mauro Carvalho Chehab <mchehab+huawei@kernel.org>
---
drivers/platform/surface/aggregator/ssh_request_layer.c | 2 +-
1 file changed, 1 insertion(+), 1 deletion(-)
From: Maximilian Luz <luzmaximilian@gmail.com> Date: 2021-01-14 14:54:08
On 1/14/21 9:04 AM, Mauro Carvalho Chehab wrote:
quoted hunk
A function has a different name between their prototype
and its kernel-doc markup:
../drivers/platform/surface/aggregator/ssh_request_layer.c:1065: warning: expecting prototype for ssh_rtl_tx_start(). Prototype was for ssh_rtl_start() instead
Signed-off-by: Mauro Carvalho Chehab <mchehab+huawei@kernel.org>
---
drivers/platform/surface/aggregator/ssh_request_layer.c | 2 +-
1 file changed, 1 insertion(+), 1 deletion(-)
Thanks! Looks good to me.
Reviewed-by: Maximilian Luz <luzmaximilian@gmail.com>
There seems to be another issue similar to this, specifically the
non-existing ssh_rtl_tx_start() and ssh_rtl_tx_start() are referenced.
Both should point to to ssh_rtl_start() instead. I'll start working on a
patch to fix that right away.
Regards,
Max
From: Hans de Goede <hidden> Date: 2021-01-18 18:23:06
Hi,
On 1/14/21 9:04 AM, Mauro Carvalho Chehab wrote:
A function has a different name between their prototype
and its kernel-doc markup:
../drivers/platform/surface/aggregator/ssh_request_layer.c:1065: warning: expecting prototype for ssh_rtl_tx_start(). Prototype was for ssh_rtl_start() instead
Signed-off-by: Mauro Carvalho Chehab <mchehab+huawei@kernel.org>
Thank you for your patch, I've applied this patch to my review-hans
branch:
https://git.kernel.org/pub/scm/linux/kernel/git/pdx86/platform-drivers-x86.git/log/?h=review-hans
Note it will show up in my review-hans branch once I've pushed my
local branch there, which might take a while.
Once I've run some tests on this branch the patches there will be
added to the platform-drivers-x86/for-next branch and eventually
will be included in the pdx86 pull-request to Linus for the next
merge-window.
Regards,
Hans
A function has a different name between their prototype
and its kernel-doc markup:
../include/drm/drm_crtc.h:1257: warning: expecting prototype for drm_crtc_alloc_with_planes(). Prototype was for drmm_crtc_alloc_with_planes() instead
Signed-off-by: Mauro Carvalho Chehab <mchehab+huawei@kernel.org>
---
include/drm/drm_crtc.h | 2 +-
1 file changed, 1 insertion(+), 1 deletion(-)
From: Simon Ser <hidden> Date: 2021-01-14 08:08:27
On Thursday, January 14th, 2021 at 9:04 AM, Mauro Carvalho Chehab [off-list ref] wrote:
A function has a different name between their prototype
and its kernel-doc markup:
../include/drm/drm_crtc.h:1257: warning: expecting prototype for drm_crtc_alloc_with_planes(). Prototype was for drmm_crtc_alloc_with_planes() instead
Signed-off-by: Mauro Carvalho Chehab <mchehab+huawei@kernel.org>
From: Simon Ser <hidden> Date: 2021-01-14 14:14:18
On Thursday, January 14th, 2021 at 9:06 AM, Simon Ser [off-list ref] wrote:
On Thursday, January 14th, 2021 at 9:04 AM, Mauro Carvalho Chehab [off-list ref] wrote:
quoted
A function has a different name between their prototype
and its kernel-doc markup:
../include/drm/drm_crtc.h:1257: warning: expecting prototype for drm_crtc_alloc_with_planes(). Prototype was for drmm_crtc_alloc_with_planes() instead
Signed-off-by: Mauro Carvalho Chehab <mchehab+huawei@kernel.org>
A function has a different name between their prototype
and its kernel-doc markup.
Signed-off-by: Mauro Carvalho Chehab <mchehab+huawei@kernel.org>
---
lib/crc7.c | 2 +-
1 file changed, 1 insertion(+), 1 deletion(-)
Some identifiers have different names between their prototypes
and the kernel-doc markup.
Acked-by: Mike Rapoport <redacted>
Signed-off-by: Mauro Carvalho Chehab <mchehab+huawei@kernel.org>
---
include/linux/memblock.h | 4 ++--
1 file changed, 2 insertions(+), 2 deletions(-)
From: Jonathan Corbet <corbet@lwn.net> Date: 2021-01-21 19:12:40
On Thu, 14 Jan 2021 09:04:36 +0100
Mauro Carvalho Chehab [off-list ref] 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