bcachefs: docs: add docs for bch2_trans_reset

Add basic kernel docs for bch2_trans_reset and bch2_trans_begin.
Signed-off-by: Dan Robertson <dan@dlrobertson.com>
Signed-off-by: Kent Overstreet <kent.overstreet@linux.dev>

fs/bcachefs/btree_iter.c

@@ -2310,6 +2310,22 @@ inline void bch2_trans_unlink_iters(struct btree_trans *trans)
 	}
 }
 
+/**
+ * bch2_trans_reset() - reset a transaction after a interrupted attempt
+ * @trans: transaction to reset
+ * @flags: transaction reset flags.
+ *
+ * While iterating over nodes or updating nodes a attempt to lock a btree
+ * node may return EINTR when the trylock fails. When this occurs
+ * bch2_trans_reset() or bch2_trans_begin() should be called and the
+ * transaction retried.
+ *
+ * Transaction reset flags include:
+ *
+ *  - TRANS_RESET_NOUNLOCK   - Do not attempt to unlock and reschedule the
+ *			       transaction.
+ *  - TRANS_RESET_NOTRAVERSE - Do not traverse all linked iters.
+ */
 void bch2_trans_reset(struct btree_trans *trans, unsigned flags)
 {
 	struct btree_iter *iter;

fs/bcachefs/btree_iter.h

@@ -319,6 +319,13 @@ static inline void set_btree_iter_dontneed(struct btree_trans *trans, struct btr
 
 void bch2_trans_reset(struct btree_trans *, unsigned);
 
+/**
+ * bch2_trans_begin() - ensure lock consistency of transaction on retry
+ * @trans: transaction to prepare
+ *
+ * Ensure lock ordering is correct before potentially retrying a transaction
+ * after a failed trylock.
+ */
 static inline void bch2_trans_begin(struct btree_trans *trans)
 {
 	return bch2_trans_reset(trans, 0);