Next set of documentation updates.

cfis · cfis · commit 17db78f3ae5b · 2026-02-22T22:55:26.000-08:00
diff --git a/docs/architecture.md b/docs/architecture.md
diff --git a/docs/cmake_bindings.md b/docs/cmake_bindings.md
@@ -1,52 +1,26 @@
 # CMake Bindings
 
-The `CMake` format generates `CMakeLists.txt` and `CMakePresets.json` files for building Rice C++ bindings. This is typically run as a second pass after generating the Rice binding source files.
+The `CMake` format generates `CMakeLists.txt` and `CMakePresets.json` files for building Rice C++ bindings. This is run as a second pass after generating the Rice binding source files.
 
-## Usage
-
-The CMake format scans the output directory for `*-rb.cpp` files produced by the Rice format and generates:
-
-- **`CMakeLists.txt`** (top-level) - Project configuration with Rice fetching, Ruby detection, and source file listing
-- **`CMakeLists.txt`** (per subdirectory) - Source file listing for each subdirectory
-- **`CMakePresets.json`** - Build presets for Linux, macOS, MSVC, MinGW, and Clang on Windows (debug and release variants)
+Rice supports building extensions with either [extconf.rb](https://ruby-rice.github.io/4.x/packaging/extconf.rb/) or [CMake](https://ruby-rice.github.io/4.x/packaging/cmake/). While `extconf.rb` works for simple bindings, CMake is vastly superior for anything more complex — it provides better cross-platform support, dependency management, and build configuration.
 
 ## Configuration
 
 ```yaml
 format: CMake
 extension: my_extension
 
-# CMake expressions for target_include_directories
 include_dirs:
   - "${CMAKE_CURRENT_SOURCE_DIR}/../headers"
 ```
 
-### Options
-
-| Option | Description |
-|--------|-------------|
-| `extension` | Project name used in `project()` and target name. Required. |
-| `include_dirs` | List of include directory expressions added via `target_include_directories`. These are written directly into CMakeLists.txt, so CMake variables like `${CMAKE_CURRENT_SOURCE_DIR}` work. |
-
-## Generated CMakeLists.txt
+See [configuration](configuration.md) for details on all options.
 
-The top-level `CMakeLists.txt` includes:
-
-- C++17 standard requirement
-- Rice fetched from GitHub via `FetchContent`
-- Ruby detection via `find_package(Ruby)`
-- Library target (SHARED on MSVC, MODULE elsewhere)
-- Extension output configuration (correct suffix, visibility settings)
-- All `*-rb.cpp` source files
-
-## Workflow
+## Usage
 
 Generate bindings in two passes:
 
 ```bash
-# Ensure output directory exists
-mkdir -p /path/to/output
-
 # 1. Generate Rice C++ source files
 ruby-bindgen rice_config.yaml
 
@@ -62,9 +36,41 @@ cmake --preset linux-debug    # or msvc-debug, macos-debug, etc.
 cmake --build build/linux-debug
 ```
 
-## Build Presets
+## Output
+
+The CMake format scans the output directory for `*-rb.cpp` files and generates:
+
+``` mermaid
+flowchart LR
+    subgraph Input
+        CF["cmake_config.yaml"]
+        S1["*-rb.cpp"]
+    end
+
+    CF & S1 --> RB["ruby-bindgen"]
+
+    subgraph "CMake Output"
+        C1["CMakeLists.txt"]
+        C2["CMakePresets.json"]
+    end
+
+    RB --> C1 & C2
+```
+
+### Top Level
 
-The generated `CMakePresets.json` includes presets for all major platforms:
+The top-level `CMakeLists.txt` is a complete project file that configures the entire build:
+
+- C++17 standard requirement
+- Rice fetched from GitHub via `FetchContent`
+- Ruby detection via `find_package(Ruby)`
+- Library target (SHARED on MSVC, MODULE elsewhere)
+- Extension output configuration (correct suffix, visibility settings)
+- Subdirectory includes and `*-rb.cpp` source file listing
+
+For a well-documented example, see the [BitmapPlusPlus-ruby CMakeLists.txt](https://github.com/ruby-rice/BitmapPlusPlus-ruby/blob/main/ext/CMakeLists.txt). For details on how Rice uses CMake, see the Rice [CMake](https://ruby-rice.github.io/4.x/packaging/cmake/) documentation.
+
+The top-level directory also gets a `CMakePresets.json` with build presets for all major platforms. For an example, see the [BitmapPlusPlus-ruby CMakePresets.json](https://github.com/ruby-rice/BitmapPlusPlus-ruby/blob/main/ext/CMakePresets.json). For details, see the Rice [CMakePresets.json](https://ruby-rice.github.io/4.x/packaging/cmake/#cmakepresetsjson) documentation.
 
 | Preset | Platform | Compiler |
 |--------|----------|----------|
@@ -74,4 +80,19 @@ The generated `CMakePresets.json` includes presets for all major platforms:
 | `mingw-debug` / `mingw-release` | Windows | MinGW GCC |
 | `clang-windows-debug` / `clang-windows-release` | Windows | clang-cl |
 
-All presets use Ninja as the build generator and include appropriate compiler flags for each platform (visibility settings, debug info, optimization levels).
+All presets use [Ninja](https://ninja-build.org/) as the build generator and include appropriate compiler flags for each platform (visibility settings, debug info, optimization levels).
+
+### Subdirectories
+
+Each subdirectory containing `*-rb.cpp` files gets a minimal `CMakeLists.txt` that lists its source files and any nested subdirectories:
+
+```cmake
+# Subdirectories
+add_subdirectory("hal")
+
+# Sources
+target_sources(${CMAKE_PROJECT_NAME} PUBLIC
+  "matrix-rb.cpp"
+  "image-rb.cpp"
+)
+```
diff --git a/docs/cpp/buffers.md b/docs/cpp/buffers.md
@@ -10,8 +10,3 @@ void getMinMax(double* min, double* max);        // Out parameters via ArgBuffer
 int* createBuffer(int size);                     // ReturnBuffer
 void processArrays(float** matrices, int count); // Double pointer via ArgBuffer
 ```
-
-This enables Ruby code to:
-- Pass buffers of data to C++ functions
-- Use out parameters for returning values
-- Work with arrays of pointers
diff --git a/docs/cpp/iterators.md b/docs/cpp/iterators.md
@@ -89,18 +89,6 @@ namespace std
 }
 ```
 
-### How It Works
-
-`ruby-bindgen` detects incomplete iterators by:
-
-1. Checking if the iterator class defines the required typedefs (`value_type`, `reference`, `pointer`, `difference_type`, `iterator_category`)
-2. If any are missing, it infers the types from the iterator's `operator*()` return type
-3. The generated traits specialization is placed at the top of the output file, before the Rice bindings code
-
-### Const Iterators
-
-`ruby-bindgen` also detects const iterators by examining the `operator*()` return type. If it returns a const reference, the generated `reference` typedef will be `const T&` instead of `T&`.
-
 ## Examples
 
 See [test/headers/cpp/iterators.hpp](../test/headers/cpp/iterators.hpp) for example iterator classes, including both complete and incomplete iterators. The generated bindings are in [test/bindings/cpp/iterators-rb.cpp](../test/bindings/cpp/iterators-rb.cpp).
diff --git a/docs/limitations.md b/docs/limitations.md
@@ -7,9 +7,9 @@ This page summarizes current limitations and constraints in `ruby-bindgen`.
 - Correct parsing depends on accurate `clang`/`clang-cl` include and language arguments.
 - Some libraries still require manual post-generation adjustments.
 
-## C++ (Rice) Generation
+## Rice Generation
 
-- Generated code is not guaranteed to compile without manual fixes for all libraries.
+- Generated code may not compile without manual fixes.
 - Default argument reconstruction is heuristic and can fail for complex C++ expressions.
 - Some APIs need explicit skipping via `skip_symbols` to avoid compile/link failures.
 - Functions/methods with unsupported signatures may be skipped (for example variadic callables).
@@ -23,13 +23,4 @@ This page summarizes current limitations and constraints in `ruby-bindgen`.
 
 ## FFI Generation
 
-- Intended for C APIs. C++ class semantics are not represented in FFI output.
 - Runtime loading depends on correct `library_names` / `library_versions` and system loader paths.
-
-## Scope
-
-`ruby-bindgen` optimizes for automating most wrapping work, then letting users handle edge cases via:
-
-- configuration filters (`skip`, `skip_symbols`, `export_macros`)
-- refinement files
-- targeted manual updates for problematic generated code
diff --git a/docs/prior_art.md b/docs/prior_art.md
@@ -10,16 +10,12 @@ This page lists related projects and adjacent tools that influenced, overlap wit
 - Scope: Multi-language binding generator for C and C++
 - Notes: Generates bindings for many languages including Ruby, Python, Java, and Go. Uses its own interface definition files rather than parsing headers directly. The most established tool in this space — active since 1996.
 
-## C
-
 ### ffi_gen
 
 - Project: [ffi_gen](https://github.com/ffi/ffi_gen)
 - Scope: Generate Ruby FFI wrappers for C APIs
 - Notes: Has not been updated in over a decade and includes liblang findings versus using [ffi-clang](https://github.com/ioquatix/ffi-clang).
 
-## C++
-
 ### rbind
 
 - Project: [rbind](https://github.com/D-Alex/rbind)
diff --git a/docs/updating_bindings.md b/docs/updating_bindings.md
@@ -2,34 +2,29 @@
 
 After generating bindings with `ruby-bindgen`, you'll need to regenerate them periodically as the upstream library evolves, `ruby-bindgen` improves, or you upgrade dependencies. This document covers strategies for managing that process.
 
-All examples below reference the [opencv-ruby](https://github.com/ruby-rice/opencv-ruby) project, which wraps OpenCV's ~350 generated files and is a good real-world reference.
+## Simple Case
 
-## Regenerate and Done
-
-The best case. Run `ruby-bindgen` again and the new output compiles and works:
+If you have no [customizations](cpp/customizing.md) to preserve, then you can simply regenerate the bindings:
 
 ```bash
 ruby-bindgen bindings.yaml
 ```
 
-This works when:
-- You're updating `ruby-bindgen` (bug fixes, new features) and don't have manual changes
-- The upstream library's API didn't change in ways that break compilation
-- Your bindings are simple enough that `ruby-bindgen` handles everything
+In most cases, the updated bindings should compile and work.
 
-If this is your situation, you're done. The sections below are for when you have [customizations](cpp/customizing.md) that need to be preserved across regenerations.
+The rest of this page discusses strategies for more complex cases where you want to preserve [customizations](cpp/customizing.md) when regenerating bindings.
 
 ## Preserving Refinements
 
-[Refinements](cpp/customizing.md#refinements-separate-manual-code) live in a separate directory that `ruby-bindgen` never touches. They survive regeneration automatically - no action needed.
+[Refinements](cpp/customizing.md#refinements-separate-manual-code) live in a separate directory that `ruby-bindgen` never touches, so the source files survive regeneration automatically. However, the top-level `-rb.cpp` file is regenerated, so you will need to re-add the `#include` directives and `Init_*_Refinement` calls.
 
 ## Preserving Manual Edits
 
-If you have [manual edits](cpp/customizing.md#manual-edits) to generated files, you need a way to reapply them after regeneration. There are two approaches:
+If you have [manual edits](cpp/customizing.md#manual-edits) to generated files, you need a way to reapply them after regeneration. Two possible approaches include:
 
 ### Option A: Diff File
 
-Maintain a unified diff file that can be reapplied after regeneration:
+Maintain a diff file that can be reapplied after regeneration:
 
 ```bash
 # After making all manual changes to generated files
@@ -51,98 +46,11 @@ git apply manual_updates.diff
 
 **Cons**: Diffs are fragile. If `ruby-bindgen`'s output changes line numbers or formatting, the diff won't apply cleanly. You'll need to manually resolve failures and regenerate the diff.
 
-### Option B: Instruction File
-
-Maintain a structured document (`manual_updates.md`) that describes each change declaratively. An AI assistant or a human can follow the instructions after each regeneration.
-
-Here's how opencv-ruby structures its `manual_updates.md`:
-
-#### Missing Includes
-
-A table mapping files to required manual includes:
-
-```markdown
-## Manual Includes
-
-| File                                     | Manual Includes                                          |
-|------------------------------------------|----------------------------------------------------------|
-| `opencv2/core/bindings_utils-rb.cpp`     | `<opencv2/core.hpp>`                                     |
-| `opencv2/core/mat-rb.cpp`               | `<opencv2/core/cuda.hpp>`, `<opencv2/core/opengl.hpp>`   |
-| `opencv2/core/saturate-rb.cpp`          | `<algorithm>`, `<climits>`                               |
-| `opencv2/flann/flann_base-rb.cpp`       | `<opencv2/core/base.hpp>`, `<opencv2/flann/defines.h>`   |
-```
-
-#### Namespace Cleanup
-
-```markdown
-## DNN Module
-
-| File                                     | Change                                                   |
-|------------------------------------------|----------------------------------------------------------|
-| `opencv2/dnn/*.cpp`, `opencv2/dnn/*.hpp` | Replace `::dnn4_v\d+` with empty string                  |
-| `opencv2/dnn/*.cpp`, `opencv2/dnn/*.hpp` | Replace `Dnn4V\d+` with empty string in variable names   |
-| `opencv2/dnn/*.cpp`                      | Delete `Module rb_mCvDnn = define_module_under(..., "");` |
-```
-
-#### Version Guards
-
-Specific line ranges to wrap with `#if` guards:
-
-```markdown
-## OpenCV Version Guards
-
-### `opencv2/core/bindings_utils-rb.cpp`
-- **Line ~38**: `dump_int64` (>= 407)
-- **Line ~113**: `dump_vec2i` through `ClassWithKeywordProperties` (>= 407)
-- **Line ~124**: `FunctionParams` class (>= 408)
+### Option B: Agent File
 
-### `opencv2/core/cvdef-rb.cpp`
-- **Line ~73**: `CV_CPU_NEON_DOTPROD` constant (>= 407)
-- **Line ~77**: `CV_CPU_NEON_FP16`, `CV_CPU_NEON_BF16` constants (>= 409)
-```
+Maintain a structured document (`manual_updates.md`) that describes each change declaratively. An AI assistant or a human can follow the instructions after each regeneration. For an example, see opencv-ruby's [manual_updates.md](https://github.com/ruby-rice/opencv-ruby/blob/main/ext/manual_updates.md).
 
 **Pros**: Survives large formatting changes, human-readable, an AI assistant can apply the instructions even when line numbers shift.
 
-**Cons**: Requires more effort to write initially. Must be kept in sync with actual changes.
-
-### Combining Both Approaches
-
-opencv-ruby maintains both files:
-
-- `manual_updates.md` - the authoritative description of what changes are needed and why
-- `manual_updates.diff` - a snapshot of the actual changes for quick verification
-
-After regeneration:
-1. Try applying the diff (`git apply manual_updates.diff`)
-2. If it fails, use `manual_updates.md` as a guide (manually or with AI)
-3. After all changes are applied, regenerate the diff:
-   ```bash
-   git diff -- ext/ ':(exclude)ext/manual_updates.md' > ext/manual_updates.diff
-   ```
-
-## Recommended Workflow
-
-For ongoing maintenance after an upstream library update:
-
-```bash
-# 1. Regenerate
-ruby-bindgen bindings.yaml
-
-# 2. Try building
-cmake --preset linux-debug && cmake --build build/linux-debug
-
-# 3. If it compiles, done. If not:
-#    - Missing includes? Add to manual_updates.md and apply
-#    - Linker errors? Comment out and document
-#    - New API version issues? Add version guards
-#    - Need custom methods? Add to refinements/
-
-# 4. Update the diff file
-git diff -- ext/ ':(exclude)ext/manual_updates.md' > ext/manual_updates.diff
-```
-
-## Tips
+**Cons**: Must be kept in sync with actual changes.
 
-- **Keep `manual_updates.md` up to date** - it's the source of truth when diffs fail to apply
-- **Refinements survive automatically** - only manual edits to generated files need tracking
-- **Try building early** - regenerate, build, and fix incrementally rather than trying to predict all issues upfront
