All of lore.kernel.org
 help / color / mirror / Atom feed
* [PATCH v2] seqlock: <linux/seqlock.h>: fix multiple kernel-doc warnings
@ 2020-08-17  0:02 Randy Dunlap
  2020-08-19  9:25 ` peterz
  2020-08-27  7:54 ` [tip: locking/core] seqlock: Fix " tip-bot2 for Randy Dunlap
  0 siblings, 2 replies; 4+ messages in thread
From: Randy Dunlap @ 2020-08-17  0:02 UTC (permalink / raw)
  To: linux-kernel; +Cc: Randy Dunlap, Peter Zijlstra, Ingo Molnar, kernel test robot

Fix kernel-doc warnings in <linux/seqlock.h>.

../include/linux/seqlock.h:152: warning: Incorrect use of kernel-doc format:  * seqcount_LOCKNAME_init() - runtime initializer for seqcount_LOCKNAME_t
../include/linux/seqlock.h:164: warning: Incorrect use of kernel-doc format:  * SEQCOUNT_LOCKTYPE() - Instantiate seqcount_LOCKNAME_t and helpers
../include/linux/seqlock.h:229: warning: Function parameter or member 'seq_name' not described in 'SEQCOUNT_LOCKTYPE_ZERO'
../include/linux/seqlock.h:229: warning: Function parameter or member 'assoc_lock' not described in 'SEQCOUNT_LOCKTYPE_ZERO'
../include/linux/seqlock.h:229: warning: Excess function parameter 'name' description in 'SEQCOUNT_LOCKTYPE_ZERO'
../include/linux/seqlock.h:229: warning: Excess function parameter 'lock' description in 'SEQCOUNT_LOCKTYPE_ZERO'
../include/linux/seqlock.h:695: warning: duplicate section name 'NOTE'

Demote kernel-doc notation for the macros "seqcount_LOCKNAME_init()" and
"SEQCOUNT_LOCKTYPE()"; scripts/kernel-doc does not handle them correctly.

Rename function parameters in SEQCNT_LOCKNAME_ZERO() documentation
to match the macro's argument names. Change the macro name in the
documentation to SEQCOUNT_LOCKTYPE_ZERO() to match the macro's name.

For raw_write_seqcount_latch(), rename the second NOTE: to NOTE2:
to prevent a kernel-doc warning. However, the generated output is not
quite as nice as it could be for this.

Fix a typo: s/LOCKTYPR/LOCKTYPE/

Fixes: 0efc94c5d15c ("seqcount: Compress SEQCNT_LOCKNAME_ZERO()")
Fixes: e4e9ab3f9f91 ("seqlock: Fold seqcount_LOCKNAME_init() definition")
Fixes: a8772dccb2ec ("seqlock: Fold seqcount_LOCKNAME_t definition")
Signed-off-by: Randy Dunlap <rdunlap@infradead.org>
Cc: Peter Zijlstra <peterz@infradead.org>
Cc: Ingo Molnar <mingo@kernel.org>
Reported-by: kernel test robot <lkp@intel.com>
---
v2: do not move the definition of seqcount_LOCKNAME_init().
Fix build errors reported by kernel test robot.
Actually build a kernel with these changes.

 include/linux/seqlock.h |   13 ++++++-------
 1 file changed, 6 insertions(+), 7 deletions(-)

--- lnx-59-rc1.orig/include/linux/seqlock.h
+++ lnx-59-rc1/include/linux/seqlock.h
@@ -138,7 +138,7 @@ static inline void seqcount_lockdep_read
 #endif
 
 /**
- * typedef seqcount_LOCKNAME_t - sequence counter with LOCKTYPR associated
+ * typedef seqcount_LOCKNAME_t - sequence counter with LOCKTYPE associated
  * @seqcount:	The real sequence counter
  * @lock:	Pointer to the associated spinlock
  *
@@ -148,7 +148,7 @@ static inline void seqcount_lockdep_read
  * that the write side critical section is properly serialized.
  */
 
-/**
+/*
  * seqcount_LOCKNAME_init() - runtime initializer for seqcount_LOCKNAME_t
  * @s:		Pointer to the seqcount_LOCKNAME_t instance
  * @lock:	Pointer to the associated LOCKTYPE
@@ -173,7 +173,6 @@ seqcount_##lockname##_init(seqcount_##lo
 	seqcount_init(&s->seqcount);					\
 	__SEQ_LOCK(s->lock = lock);					\
 }									\
-									\
 static __always_inline seqcount_t *					\
 __seqcount_##lockname##_ptr(seqcount_##lockname##_t *s)			\
 {									\
@@ -218,9 +217,9 @@ SEQCOUNT_LOCKTYPE(struct mutex,		mutex,
 SEQCOUNT_LOCKTYPE(struct ww_mutex,	ww_mutex,	true,	&s->lock->base)
 
 /**
- * SEQCNT_LOCKNAME_ZERO - static initializer for seqcount_LOCKNAME_t
- * @name:	Name of the seqcount_LOCKNAME_t instance
- * @lock:	Pointer to the associated LOCKTYPE
+ * SEQCOUNT_LOCKTYPE_ZERO - static initializer for seqcount_LOCKNAME_t
+ * @seq_name:	Name of the seqcount_LOCKNAME_t instance
+ * @assoc_lock:	Pointer to the associated LOCKTYPE
  */
 
 #define SEQCOUNT_LOCKTYPE_ZERO(seq_name, assoc_lock) {			\
@@ -688,7 +687,7 @@ static inline int raw_read_seqcount_t_la
  *	to miss an entire modification sequence, once it resumes it might
  *	observe the new entry.
  *
- * NOTE:
+ * NOTE2:
  *
  *	When data is a dynamic data structure; one should use regular RCU
  *	patterns to manage the lifetimes of the objects within.

^ permalink raw reply	[flat|nested] 4+ messages in thread

end of thread, other threads:[~2020-08-27  7:57 UTC | newest]

Thread overview: 4+ messages (download: mbox.gz / follow: Atom feed)
-- links below jump to the message on this page --
2020-08-17  0:02 [PATCH v2] seqlock: <linux/seqlock.h>: fix multiple kernel-doc warnings Randy Dunlap
2020-08-19  9:25 ` peterz
2020-08-19 16:52   ` Randy Dunlap
2020-08-27  7:54 ` [tip: locking/core] seqlock: Fix " tip-bot2 for Randy Dunlap

This is an external index of several public inboxes,
see mirroring instructions on how to clone and mirror
all data and code used by this external index.