add more docs

Author: cmazakas

fix.py

@@ -0,0 +1,51 @@
+import re
+import sys
+from pathlib import Path
+
+def process(text: str) -> str:
+    # 1. Remove the "# NAME" line entirely
+    text = re.sub(r'^# NAME\s*\n', '', text, flags=re.MULTILINE)
+
+    # 2. Extract the short description line:
+    #    e.g. "io_uring_for_each_cqe - iterate pending completion events"
+    m = re.search(r'^(.*?)\s*-\s*(.*)$', text, flags=re.MULTILINE)
+    if m:
+        short = m.group(2).strip()
+        # Capitalize first word
+        short = short[0].upper() + short[1:]
+        # Ensure trailing period
+        if not short.endswith('.'):
+            short += '.'
+        # Replace the whole line with just the cleaned short description
+        text = re.sub(r'^.*? - .*$', short, text, flags=re.MULTILINE)
+
+    # 3. Remove everything from "# SYNOPSIS" up to "# DESCRIPTION"
+    text = re.sub(
+        r'# SYNOPSIS[\s\S]*?# DESCRIPTION',
+        '# DESCRIPTION',
+        text,
+        flags=re.MULTILINE
+    )
+
+    # 4. Transform SEE ALSO entries:
+    #    **symbol**(3) → [symbol]
+    def fix_see_also(match):
+        symbol = match.group(1)
+        return f'[{symbol}]'
+
+    text = re.sub(
+        r'\*\*([A-Za-z0-9_]+)\*\*\(\d+\)',
+        fix_see_also,
+        text
+    )
+
+    return text
+
+if __name__ == "__main__":
+    for path in sys.argv[1:]:
+        p = Path(path)
+        original = p.read_text()
+        cleaned = process(original)
+        print(cleaned)
+        p.write_text(cleaned)
+        print(f"Processed {p}")

liburing-rs/README.md

@@ -93,7 +93,6 @@ use std::{mem::zeroed, ptr, time::Duration};
 
 use liburing_rs::*;
 
-#[test]
 pub fn queue_init() {
     // Setup the ring.
     //

liburing-rs/docs/IO_URING_VERSION_MAJOR.md

@@ -0,0 +1,24 @@
+Functions and macros to check the liburing.
+version
+
+# DESCRIPTION
+
+The [io_uring_check_version] function returns *false* if the
+liburing library loaded by the dynamic linker is greater-than or
+equal-to the *major* and *minor* numbers provided.
+
+The [IO_URING_CHECK_VERSION] macro returns *0* if the liburing
+library being compiled against is greater-than or equal-to the *major*
+and *minor* numbers provided.
+
+The [io_uring_major_version] function returns the *major* version
+number of the liburing library loaded by the dynamic linker.
+
+The [IO_URING_VERSION_MAJOR] macro returns the *major* version
+number of the liburing library being compiled against.
+
+The [io_uring_minor_version] function returns the *minor* version
+number of the liburing library loaded by the dynamic linker.
+
+The [IO_URING_VERSION_MINOR] macro returns the *minor* version
+number of the liburing library being compiled against.

liburing-rs/docs/IO_URING_VERSION_MINOR.md

@@ -0,0 +1,24 @@
+Functions and macros to check the liburing.
+version
+
+# DESCRIPTION
+
+The [io_uring_check_version] function returns *false* if the
+liburing library loaded by the dynamic linker is greater-than or
+equal-to the *major* and *minor* numbers provided.
+
+The [IO_URING_CHECK_VERSION] macro returns *0* if the liburing
+library being compiled against is greater-than or equal-to the *major*
+and *minor* numbers provided.
+
+The [io_uring_major_version] function returns the *major* version
+number of the liburing library loaded by the dynamic linker.
+
+The [IO_URING_VERSION_MAJOR] macro returns the *major* version
+number of the liburing library being compiled against.
+
+The [io_uring_minor_version] function returns the *minor* version
+number of the liburing library loaded by the dynamic linker.
+
+The [IO_URING_VERSION_MINOR] macro returns the *minor* version
+number of the liburing library being compiled against.

liburing-rs/docs/io_uring.md

@@ -107,7 +107,7 @@ or posting multiple CQEs for a single SQE for multi shot operations or
 requiring an **io_uring_enter**(2) syscall to make the kernel begin
 processing newly added SQEs when using submission queue polling.
 
-## Submission queue polling
+**Submission**\ queue polling
 
 One of the goals of **io_uring** is to provide a means for efficient
 I/O. To this end, **io_uring** supports a polling mode that lets you
@@ -120,7 +120,7 @@ avoid the overhead of system calls. A designated kernel thread dequeues
 SQEs off the SQ as you add them and dispatches them for asynchronous
 processing.
 
-## Setting up io_uring
+**Setting**\ up io_uring
 
 The main steps in setting up **io_uring** consist of mapping in the
 shared buffers with **mmap**(2) calls. In the example program included
@@ -130,7 +130,7 @@ the 2 **mmap**(2) calls that set up the shared submission and completion
 queues. If your kernel is older than version 5.4, three **mmap(2)**
 calls are required.
 
-## Submitting I/O requests
+**Submitting**\ I/O requests
 
 The process of submitting a request consists of describing the I/O
 operation you need to get done using an **io_uring_sqe** structure
@@ -313,7 +313,7 @@ waiting for a specified count of events to complete. This way, you can
 be sure to find completion events in the completion queue without having
 to poll it for events later.
 
-## SQE pointer lifetimes & data stability
+**SQE**\ pointer lifetimes & data stability
 
 Due to the fixed size of the submission queue entry (SQE) some data you
 provide in order to perform a desired operation will be passed in the
@@ -342,7 +342,7 @@ read or written while the operation is inflight. For example, the
 pointers to a buffer used as part of a **IORING_OP_WRITE** or
 **IORING_OP_READ** operation must remain valid until completion.
 
-## Reading completion events
+**Reading**\ completion events
 
 Similar to the submission queue (SQ), the completion queue (CQ) is a
 shared buffer between the kernel and user space. Whereas you placed
@@ -458,7 +458,7 @@ the head needs to be updated to reflect the consumption of the CQE.
 Attention should be paid to the read and write barriers to ensure
 successful read and update of the head.
 
-## io_uring performance
+**io_uring**\ performance
 
 Because of the shared ring buffers between kernel and user space,
 **io_uring** can be a zero-copy system. Copying buffers to and from

liburing-rs/docs/io_uring_buf_ring_cq_advance.md

@@ -11,6 +11,11 @@ call and a **io_uring_cq_advance**(3) into one operation. Since updating
 either ring index entails a store memory barrier, doing both at once is
 more efficient.
 
+The **\_\_io_uring_buf_ring_cq_advance**(3) function performs the same
+operation, except it splits the counts into two separate values. It
+advances the CQ ring by *cq_count* entries, and the buffer ring by
+*buf_count* entries rather than increment both by the same value.
+
 # RETURN VALUE
 
 None

liburing-rs/docs/io_uring_clone_buffers.md

@@ -45,15 +45,15 @@ for **\_\_io_uring_clone_buffers**(3) for details.
 
 *flags* may be set to the following value:
 
-## IORING_REGISTER_SRC_REGISTERED
+**IORING_REGISTER_SRC_REGISTERED**\
 
 If the source ring is registered AND the calling thread is the one that
 originally registered its ring fd, then this flag may be set to lookup
 the registered index rather than use the normal file descriptor. If the
 normal file descriptor wasn't closed after registering it, there's no
 need to set this flag.
 
-## IORING_REGISTER_DST_REPLACE
+**IORING_REGISTER_DST_REPLACE**\
 
 If set, cloning may happen for a destination ring that already has a
 buffer table assigned. In that case, existing nodes that overlap with

liburing-rs/docs/io_uring_cqe_get_data.md

@@ -0,0 +1,26 @@
+Get user data for completion event.
+
+# DESCRIPTION
+
+The **io_uring_cqe_get_data**(3) function returns the user_data with the
+completion queue entry *cqe* as a data pointer.
+
+The **io_uring_cqe_get_data64**(3) function returns the user_data with
+the completion queue entry *cqe* as a 64-bit data value.
+
+After the caller has received a completion queue entry (CQE) with
+**io_uring_wait_cqe**(3), the application can call
+**io_uring_cqe_get_data**(3) or **io_uring_cqe_get_data64**(3) function
+to retrieve the *user_data* value. This requires that *user_data* has
+been set earlier with the function **io_uring_sqe_set_data**(3) or
+**io_uring_sqe_set_data64**(3).
+
+# RETURN VALUE
+
+If the *user_data* value has been set before submitting the request, it
+will be returned. Otherwise, the return value is undefined.
+
+# SEE ALSO
+
+[io_uring_get_sqe], [io_uring_sqe_set_data],
+[io_uring_submit]

liburing-rs/docs/io_uring_cqe_nr.md

@@ -0,0 +1,20 @@
+Return the number of CQ ring slots consumed by a CQE.
+
+# DESCRIPTION
+
+The **io_uring_cqe_nr**(3) function returns the number of CQ ring slots
+consumed by *cqe*. For normal 16-byte CQEs, this returns 1. For 32-byte
+CQEs (when **IORING_CQE_F_32** is set in the CQE flags), this returns 2.
+
+This function is useful when advancing the CQ ring with
+**io_uring_cq_advance**(3) on rings that use **IORING_SETUP_CQE_MIXED**
+where both 16-byte and 32-byte CQEs may be present.
+
+# RETURN VALUE
+
+Returns 1 for normal CQEs, or 2 for 32-byte CQEs.
+
+# SEE ALSO
+
+[io_uring_cq_advance], [io_uring_cqe_seen],
+[io_uring_setup]

liburing-rs/docs/io_uring_cqe_seen.md

@@ -0,0 +1,24 @@
+Mark io_uring completion event as consumed.
+
+# DESCRIPTION
+
+The **io_uring_cqe_seen**(3) function marks the IO completion *cqe*
+belonging to the *ring* param as consumed.
+
+After the caller has submitted a request with **io_uring_submit**(3),
+the application can retrieve the completion with
+**io_uring_wait_cqe**(3), **io_uring_peek_cqe**(3), or any of the other
+CQE retrieval helpers, and mark it as consumed with
+**io_uring_cqe_seen**(3).
+
+Completions must be marked as completed so their slot can get reused.
+
+# RETURN VALUE
+
+None
+
+# SEE ALSO
+
+[io_uring_submit], [io_uring_peek_cqe],
+[io_uring_wait_cqe], [io_uring_wait_cqes],
+[io_uring_wait_cqe_timeout]