lkml.org 
[lkml]   [2020]   [Oct]   [13]   [last100]   RSS Feed
Views: [wrap][no wrap]   [headers]  [forward] 
 
Messages in this thread
Patch in this message
/
From
Subject[PATCH v2 16/24] seqlock: fix two kernel-doc warnings
Date
Right now, seqloc.h produces two kernel-doc warnings:

./include/linux/seqlock.h:181: error: Cannot parse typedef!
WARNING: kernel-doc './scripts/kernel-doc -rst -enable-lineno ./include/linux/seqlock.h' failed with return code 1

Those are due to two things:

1. the kernel-doc markup syntax doesn't recognize "typedef"
expression at the markup. Both functions and typedefs
use the same notation:

/**
* foo - some bar description
*/
or
/**
* foo() - some bar description
*/

2. kernel-doc markups require a function or typedef prototype,
in order to get the type of each argument. This is also
common for other code documentation markkup languages, like
doxygen.

On other words, a valid notation for describing those macros
would be:

/**
* seqcount_LOCKNAME_t() - sequence counter with LOCKNAME associated
* @seqcount: The real sequence counter
* @lock: Pointer to the associated lock
*
* <some description>
*/
#if 0 /* kernel-doc needs a function or typedef prototype */
void seqcount_LOCKNAME_t(seqcount_##lockname##_t *seqcount, locktype *lock) {}
#endif

Alternatively, the description of those arguments should be added
as a DOC: block.

Yet, from changeset a28e884b966e ("seqlock: Fix multiple kernel-doc warnings"),
it sounds that, on this file, it is preferred to just convert the
kernel-doc markups into simple comments.

Fixes: a8772dccb2ec ("seqlock: Fold seqcount_LOCKNAME_t definition")
Signed-off-by: Mauro Carvalho Chehab <mchehab+huawei@kernel.org>
---
include/linux/seqlock.h | 2 +-
1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/include/linux/seqlock.h b/include/linux/seqlock.h
index ac5b07f558b0..cbfc78b92b65 100644
--- a/include/linux/seqlock.h
+++ b/include/linux/seqlock.h
@@ -154,7 +154,7 @@ static inline void seqcount_lockdep_reader_access(const seqcount_t *s)
#define __SEQ_LOCK(expr)
#endif

-/**
+/*
* typedef seqcount_LOCKNAME_t - sequence counter with LOCKNAME associated
* @seqcount: The real sequence counter
* @lock: Pointer to the associated lock
--
2.26.2
\
 
 \ /
  Last update: 2020-10-13 14:15    [W:0.491 / U:0.344 seconds]
©2003-2020 Jasper Spaans|hosted at Digital Ocean and TransIP|Read the blog|Advertise on this site