Enhance documentation and improve code readability

.github/workflows/doxygen.yml

@@ -0,0 +1,35 @@
+name: Build Documentation
+
+on:
+  push:
+    branches: [ main ]
+  pull_request:
+
+  # Allows running this workflow manually from the Actions tab.
+  workflow_dispatch:
+
+permissions:
+  contents: write
+
+jobs:
+  generate-docs:
+    concurrency: ci-${{ github.ref }}
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout 🛎️
+        uses: actions/checkout@v4
+
+      - name: Install Doxygen and Dependencies 📦
+        run: |
+          sudo apt-get update
+          sudo apt-get install -y doxygen graphviz mscgen dia
+
+      - name: Generate Documentation 🔧
+        run: |
+          cmake -S . -B build
+          cmake --build build --target doxy
+
+      - name: Deploy Pages 🚀
+        uses: JamesIves/github-pages-deploy-action@v4
+        with:
+          folder: build/html

CMakeLists.txt

@@ -39,7 +39,11 @@ add_test(NAME left_shift_edge COMMAND test_runner test/left_shift_edge)
 # https://www.mcternan.me.uk/mscgen/
 find_package(Doxygen OPTIONAL_COMPONENTS dot mscgen dia)
 if(DOXYGEN_FOUND)
+    set(DOXYGEN_USE_MDFILE_AS_MAINPAGE README.md)
     set(DOXYGEN_OPTIMIZE_OUTPUT_FOR_C YES)
     set(DOXYGEN_SOURCE_BROWSER YES)
-    doxygen_add_docs(doxy ${PROJECT_SOURCE_DIR}/inc ${PROJECT_SOURCE_DIR}/src)
+    set(DOXYGEN_EXCLUDE ${CMAKE_BINARY_DIR})
+    doxygen_add_docs(doxy ${CMAKE_SOURCE_DIR}
+        COMMENT "Generating API documentation with Doxygen"
+    )
 endif()

README.md

@@ -1,9 +1,3 @@
----
-editor_options:
-  markdown:
-    wrap: 72
----
-
 # Blit
 
 Blit (bit-block transfer) operations on planes of bits. This library
@@ -70,7 +64,7 @@ unsigned integers (`blit_scanline_t` type). Key properties:
 
 **Example:**
 
-``` c
+```c
 BLIT_SCAN_DEFINE(image, 800, 600); // 800×600 bit image
 ```
 
@@ -100,7 +94,7 @@ All 16 binary operations combining source (S) and destination (D):
 
 Common operations have aliases:
 
-``` c
+```c
 blit_rop2_copy = blit_rop2_S
 blit_rop2_invert = blit_rop2_Sn
 blit_rop2_xor = blit_rop2_DSx
@@ -119,7 +113,7 @@ Handles efficient bit-level alignment between source and destination:
 
 ### Low-Level API: `blit_rgn1_rop2`
 
-``` c
+```c
 bool blit_rgn1_rop2(struct blit_scan *result,
                     struct blit_rgn1 *x,
                     struct blit_rgn1 *y,
@@ -142,7 +136,7 @@ bool blit_rgn1_rop2(struct blit_scan *result,
 
 ### Convenience API: `blit_rop2`
 
-``` c
+```c
 bool blit_rop2(struct blit_scan *result,
                int x, int y, int x_extent, int y_extent,
                const struct blit_scan *source,
@@ -168,7 +162,7 @@ region inspection
 
 ### Copy a 32×32 region
 
-``` c
+```c
 BLIT_SCAN_DEFINE(dest, 256, 256);
 BLIT_SCAN_DEFINE(source, 256, 256);
 
@@ -178,14 +172,14 @@ blit_rop2(&dest, 50, 50, 32, 32, &source, 100, 50, blit_rop2_copy);
 
 ### Invert a region
 
-``` c
+```c
 // Invert a 64×64 area at (0,0) in an image.
 blit_rop2(&image, 0, 0, 64, 64, &image, 0, 0, blit_rop2_invert);
 ```
 
 ### XOR pattern overlay
 
-``` c
+```c
 BLIT_SCAN_DEFINE(pattern, 8, 8);
 BLIT_SCAN_DEFINE(canvas, 640, 480);
 
@@ -199,7 +193,7 @@ for (int y = 0; y < 480; y += 8) {
 
 ### Using region structures (advanced)
 
-``` c
+```c
 struct blit_rgn1 x_rgn = {.origin = 10, .extent = 50, .origin_source = 20};
 struct blit_rgn1 y_rgn = {.origin = 10, .extent = 50, .origin_source = 20};
 
@@ -218,7 +212,7 @@ if (blit_rgn1_rop2(&dest, &x_rgn, &y_rgn, &source, blit_rop2_and)) {
 
 ### Build Commands
 
-``` bash
+```bash
 mkdir build
 cd build
 cmake ..
@@ -227,7 +221,7 @@ cmake --build .
 
 ### Running Tests
 
-``` bash
+```bash
 cd build
 ctest                    # Run all tests
 ctest --verbose          # With detailed output
@@ -242,7 +236,7 @@ Each of the 16 ROP2 codes maps to a static function implementing the
 bitwise operation. Take one example: the DSx (destination XOR source in
 reverse Polish) operation:
 
-``` c
+```c
 // Example: DSx (XOR) operation.
 static blit_scanline_t ropDSx(blit_scanline_t fetch, blit_scanline_t store) {
   return fetch ^ store;
@@ -300,7 +294,7 @@ combinations.
 
 Run all tests using the following:
 
-``` bash
+```bash
 cd build
 ctest --verbose
 ```

inc/blit/rgn1.h

@@ -11,7 +11,7 @@
  * clipping the region.
  */
 
- #ifndef __BLIT_RGN1_H__
+#ifndef __BLIT_RGN1_H__
 #define __BLIT_RGN1_H__
 
 #include <assert.h>
@@ -61,9 +61,23 @@ static inline void blit_rgn1_norm(struct blit_rgn1 *rgn1) {
   assert(rgn1->extent >= 0);
 }
 
+/*!
+ * \brief Slip a one-dimensional region into positive space.
+ * \details This function adjusts a one-dimensional region represented by the
+ * \c blit_rgn1 structure to ensure that both the origin and source origin are
+ * non-negative. If either the origin or source origin is negative, the region
+ * is "slipped" into positive space by adjusting the origins and reducing the
+ * extent accordingly. If the entire region is outside positive space, the
+ * function returns false.
+ * \param rgn1 Pointer to the \c blit_rgn1 structure to slip.
+ * \retval true if the region was successfully slipped into positive space.
+ * \retval false if the entire region is outside positive space.
+ */
 static inline bool blit_rgn1_slip(struct blit_rgn1 *rgn1) {
-  int offset =
-      rgn1->origin < 0 ? (rgn1->origin < rgn1->origin_source ? -rgn1->origin : -rgn1->origin_source) : (rgn1->origin_source < 0 ? -rgn1->origin_source : 0);
+  int offset = rgn1->origin < 0
+                   ? (rgn1->origin < rgn1->origin_source ? -rgn1->origin
+                                                         : -rgn1->origin_source)
+                   : (rgn1->origin_source < 0 ? -rgn1->origin_source : 0);
   assert(offset >= 0);
   if (offset >= rgn1->extent)
     return false;