Kernel-doc currently expects that the kernel-doc markup to come
just before the function 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 function identifiers, warning about
wrong identifiers and not documenting them.
Signed-off-by: Mauro Carvalho Chehab <mchehab+huawei@xxxxxxxxxx>
---
scripts/kernel-doc | 9 ++++++++-
1 file changed, 8 insertions(+), 1 deletion(-)
diff --git a/scripts/kernel-doc b/scripts/kernel-doc
index 99cd8418ff8a..c879e69262dd 100755
--- a/scripts/kernel-doc
+++ b/scripts/kernel-doc
@@ -382,6 +382,9 @@ my $inline_doc_state;
# 'function', 'struct', 'union', 'enum', 'typedef'
my $decl_type;
+# On functions, this should match the name of the function
+my $identifier;
+
my $doc_start = '^/\*\*\s*$'; # Allow whitespace at end of comment start.
my $doc_end = '\*/';
my $doc_com = '\s*\*\s*';
@@ -1785,6 +1788,11 @@ sub dump_function($$) {
$declaration_name = $2;
my $args = $3;
+ if ($identifier ne $declaration_name) {
+ print STDERR "${file}:$.: warning: expecting prototype for function $identifier. Prototype was for function $declaration_name instead\n";
+ return;
+ }
+
create_parameterlist($args, ',', $file, $declaration_name);
} else {
print STDERR "${file}:$.: warning: cannot understand function prototype: '$prototype'\n";
@@ -2036,7 +2044,6 @@ sub process_normal() {
#
sub process_name($$) {
my $file = shift;
- my $identifier;
my $descr;
if (/$doc_block/o) {
--
2.26.2
