From 370df37596ef86acddc3ad30f8b6b7a109e1f3e9 Mon Sep 17 00:00:00 2001
From: Max Kellermann <max.kellermann@ionos.com>
Date: Mon, 11 Nov 2024 17:44:09 +0100
Subject: [PATCH] io/uring/Ring: add more API documentation

---
 src/io/uring/Ring.hxx | 32 ++++++++++++++++++++++++++++++++
 1 file changed, 32 insertions(+)

diff --git a/src/io/uring/Ring.hxx b/src/io/uring/Ring.hxx
index 0cdeb1153..24ea3c6c6 100644
--- a/src/io/uring/Ring.hxx
+++ b/src/io/uring/Ring.hxx
@@ -19,6 +19,11 @@ class Ring {
 	struct io_uring ring;
 
 public:
+	/**
+	 * Construct the io_uring using io_uring_queue_init().
+	 *
+	 * Throws on error.
+	 */
 	Ring(unsigned entries, unsigned flags);
 
 	~Ring() noexcept {
@@ -28,23 +33,50 @@ public:
 	Ring(const Ring &) = delete;
 	Ring &operator=(const Ring &) = delete;
 
+	/**
+	 * Returns the io_uring file descriptor.
+	 */
 	FileDescriptor GetFileDescriptor() const noexcept {
 		return FileDescriptor(ring.ring_fd);
 	}
 
+	/**
+	 * Returns a submit queue entry or nullptr if the submit queue
+	 * is full.
+	 */
 	struct io_uring_sqe *GetSubmitEntry() noexcept {
 		return io_uring_get_sqe(&ring);
 	}
 
+	/**
+	 * Submit all pending entries from the submit queue to the
+	 * kernel using io_uring_submit().
+	 *
+	 * Throws on error.
+	 */
 	void Submit();
 
+	/**
+	 * Waits for one completion.
+	 *
+	 * Throws on error.
+	 *
+	 * @return a completion queue entry or nullptr on EAGAIN
+	 */
 	struct io_uring_cqe *WaitCompletion();
 
 	/**
+	 * Peek one completion (non-blocking).
+	 *
+	 * Throws on error.
+	 *
 	 * @return a completion queue entry or nullptr on EAGAIN
 	 */
 	struct io_uring_cqe *PeekCompletion();
 
+	/**
+	 * Mark one completion event as consumed.
+	 */
 	void SeenCompletion(struct io_uring_cqe &cqe) noexcept {
 		io_uring_cqe_seen(&ring, &cqe);
 	}