seqlock: Properly format kernel-doc code samples

Align the code samples and note sections inside kernel-doc comments with
tabs. This way they can be properly parsed and rendered by Sphinx. It
also makes the code samples easier to read from text editors.

Signed-off-by: Ahmed S. Darwish <a.darwish@linutronix.de>
Signed-off-by: Peter Zijlstra (Intel) <peterz@infradead.org>
Link: https://lkml.kernel.org/r/20200720155530.1173732-3-a.darwish@linutronix.de

diff --git a/include/linux/seqlock.h b/include/linux/seqlock.h
index 299d68f..6c4f68e 100644 (file)
--- a/include/linux/seqlock.h
+++ b/include/linux/seqlock.h
@@ -263,32 +263,32 @@ static inline void raw_write_seqcount_end(seqcount_t *s)
  * atomically, avoiding compiler optimizations; b) to document which writes are
  * meant to propagate to the reader critical section. This is necessary because
  * neither writes before and after the barrier are enclosed in a seq-writer
- * critical section that would ensure readers are aware of ongoing writes.
+ * critical section that would ensure readers are aware of ongoing writes::
  *
- *      seqcount_t seq;
- *      bool X = true, Y = false;
+ *     seqcount_t seq;
+ *     bool X = true, Y = false;
  *
- *      void read(void)
- *      {
- *              bool x, y;
+ *     void read(void)
+ *     {
+ *             bool x, y;
  *
- *              do {
- *                      int s = read_seqcount_begin(&seq);
+ *             do {
+ *                     int s = read_seqcount_begin(&seq);
  *
- *                      x = X; y = Y;
+ *                     x = X; y = Y;
  *
- *              } while (read_seqcount_retry(&seq, s));
+ *             } while (read_seqcount_retry(&seq, s));
  *
- *              BUG_ON(!x && !y);
+ *             BUG_ON(!x && !y);
  *      }
  *
  *      void write(void)
  *      {
- *              WRITE_ONCE(Y, true);
+ *             WRITE_ONCE(Y, true);
  *
- *              raw_write_seqcount_barrier(seq);
+ *             raw_write_seqcount_barrier(seq);
  *
- *              WRITE_ONCE(X, false);
+ *             WRITE_ONCE(X, false);
  *      }
  */
 static inline void raw_write_seqcount_barrier(seqcount_t *s)
@@ -325,64 +325,68 @@ static inline int raw_read_seqcount_latch(seqcount_t *s)
  * Very simply put: we first modify one copy and then the other. This ensures
  * there is always one copy in a stable state, ready to give us an answer.
  *
- * The basic form is a data structure like:
+ * The basic form is a data structure like::
  *
- * struct latch_struct {
- *     seqcount_t              seq;
- *     struct data_struct      data[2];
- * };
+ *     struct latch_struct {
+ *             seqcount_t              seq;
+ *             struct data_struct      data[2];
+ *     };
  *
  * Where a modification, which is assumed to be externally serialized, does the
- * following:
+ * following::
  *
- * void latch_modify(struct latch_struct *latch, ...)
- * {
- *     smp_wmb();      <- Ensure that the last data[1] update is visible
- *     latch->seq++;
- *     smp_wmb();      <- Ensure that the seqcount update is visible
+ *     void latch_modify(struct latch_struct *latch, ...)
+ *     {
+ *             smp_wmb();      // Ensure that the last data[1] update is visible
+ *             latch->seq++;
+ *             smp_wmb();      // Ensure that the seqcount update is visible
  *
- *     modify(latch->data[0], ...);
+ *             modify(latch->data[0], ...);
  *
- *     smp_wmb();      <- Ensure that the data[0] update is visible
- *     latch->seq++;
- *     smp_wmb();      <- Ensure that the seqcount update is visible
+ *             smp_wmb();      // Ensure that the data[0] update is visible
+ *             latch->seq++;
+ *             smp_wmb();      // Ensure that the seqcount update is visible
  *
- *     modify(latch->data[1], ...);
- * }
+ *             modify(latch->data[1], ...);
+ *     }
  *
- * The query will have a form like:
+ * The query will have a form like::
  *
- * struct entry *latch_query(struct latch_struct *latch, ...)
- * {
- *     struct entry *entry;
- *     unsigned seq, idx;
+ *     struct entry *latch_query(struct latch_struct *latch, ...)
+ *     {
+ *             struct entry *entry;
+ *             unsigned seq, idx;
  *
- *     do {
- *             seq = raw_read_seqcount_latch(&latch->seq);
+ *             do {
+ *                     seq = raw_read_seqcount_latch(&latch->seq);
  *
- *             idx = seq & 0x01;
- *             entry = data_query(latch->data[idx], ...);
+ *                     idx = seq & 0x01;
+ *                     entry = data_query(latch->data[idx], ...);
  *
- *             smp_rmb();
- *     } while (seq != latch->seq);
+ *                     smp_rmb();
+ *             } while (seq != latch->seq);
  *
- *     return entry;
- * }
+ *             return entry;
+ *     }
  *
  * So during the modification, queries are first redirected to data[1]. Then we
  * modify data[0]. When that is complete, we redirect queries back to data[0]
  * and we can modify data[1].
  *
- * NOTE: The non-requirement for atomic modifications does _NOT_ include
- *       the publishing of new entries in the case where data is a dynamic
- *       data structure.
+ * NOTE:
+ *
+ *     The non-requirement for atomic modifications does _NOT_ include
+ *     the publishing of new entries in the case where data is a dynamic
+ *     data structure.
+ *
+ *     An iteration might start in data[0] and get suspended long enough
+ *     to miss an entire modification sequence, once it resumes it might
+ *     observe the new entry.
  *
- *       An iteration might start in data[0] and get suspended long enough
- *       to miss an entire modification sequence, once it resumes it might
- *       observe the new entry.
+ * NOTE:
  *
- * NOTE: When data is a dynamic data structure; one should use regular RCU
- *       patterns to manage the lifetimes of the objects within.
+ *     When data is a dynamic data structure; one should use regular RCU
+ *     patterns to manage the lifetimes of the objects within.
  */
 static inline void raw_write_seqcount_latch(seqcount_t *s)
 {