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@xxxxxxxxxx>
---
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
