Docs (3)

.github/workflows/ruby.yml

@@ -18,6 +18,10 @@ on:
       - master
       - dev
       - boilerplate
+      - doc
+      - doc.1
+      - doc.2
+      - doc.3
       - idiomatic
       - rc1
       - rc2
@@ -32,6 +36,26 @@ defaults:
     shell: bash
 
 jobs:
+
+  documentation:
+
+    name: Documentation
+
+    runs-on: ubuntu-latest
+
+    steps:
+    - name: Checking out code
+      uses: actions/checkout@v7
+
+    - name: Set up Ruby
+      uses: ruby/setup-ruby@v1
+      with:
+        ruby-version: '3.4'
+        bundler-cache: false
+
+    - name: Generate RDoc coverage report
+      run: ./generate_rdoc.sh -C
+
   test:
 
     strategy:

docs/reference/README.md

@@ -0,0 +1,37 @@
+# xqsr3 Generated API Reference <!-- omit in toc -->
+
+The generated API reference is produced by RDoc from the Ruby source
+documentation comments. It complements the authored guides and component
+catalogue:
+
+* [`docs/components/`](../components/README.md) explains component selection
+  and behaviour;
+* [`docs/guides/`](../guides/README.md) explains task-oriented workflows;
+* generated `doc/` explains the complete public Ruby API.
+
+
+## Generate the reference
+
+From the project root, run:
+
+```Shell
+./generate_rdoc.sh
+```
+
+The script removes any previous generated output and writes the new reference
+to `doc/`. The generated files are build output and should not be edited by
+hand.
+
+
+## Reading the reference
+
+Use the generated namespace and method pages for exact signatures and
+source-level API details. Start with the authored documentation when deciding
+which component to use, then use RDoc to inspect the complete method surface.
+
+The RDoc index is anchored by **lib/xqsr3/doc_.rb**, which provides the
+cross-component namespace overview. Public implementation comments remain the
+authoritative source for signatures, options, and exceptions.
+
+
+<!-- ########################### end of file ########################### -->

generate_rdoc.sh

@@ -6,7 +6,7 @@
 # Purpose:  Generates documentation
 #
 # Created:  11th June 2016
-# Updated:  14th August 2026
+# Updated:  28th August 2026
 #
 #############################################################################
 
@@ -20,6 +20,8 @@ rdoc \
   -x *.gemspec \
   \
   -x doc/ \
+  -x docs/ \
+  -x examples/ \
   -x gems/ \
   -x old-gems/ \
   -x test/performance/ \

lib/xqsr3/conversion/bool_parser.rb

@@ -5,7 +5,7 @@
 # Purpose:  Definition of the ::Xqsr3::Conversion::BoolParser module
 #
 # Created:  3rd June 2017
-# Updated:  19th August 2026
+# Updated:  28th August 2026
 #
 # Home:     https://github.com/synesissoftware/xqsr3
 #
@@ -55,7 +55,7 @@ module Conversion
   module BoolParser
 
     private
-    def self.matches_to_ s, expr
+    def self.matches_to_ s, expr # :nodoc:
 
       case expr
       when ::Regexp

lib/xqsr3/doc_.rb

@@ -5,7 +5,7 @@
 # Purpose:  Documentation of the ::Xqsr3 modules
 #
 # Created:  10th June 2016
-# Updated:  19th August 2026
+# Updated:  28th August 2026
 #
 # Home:     https://github.com/synesissoftware/xqsr3
 #
@@ -75,11 +75,19 @@ module CommandLineUtilities
 
   # Containers
   #
+  # === Subordinate modules of interest
+  # * ::Xqsr3::Containers::FrequencyMap
+  # * ::Xqsr3::Containers::MultiMap
+  #
   module Containers
   end # module Containers
 
   # Conversion
   #
+  # === Subordinate modules of interest
+  # * ::Xqsr3::Conversion::BoolParser
+  # * ::Xqsr3::Conversion::IntegerParser
+  #
   module Conversion
   end # module Conversion
 
@@ -121,14 +129,21 @@ module Exceptions
   # * ::Xqsr3::HashUtilities::KeyMatching
   module HashUtilities
 
-    # Exception-related utilities
+    # Deep hash transformation
     #
     # === Components of interest
-    # * ::Xqsr3::Diagnostics::HashUtilities::deep_transform
-    # * ::Xqsr3::Diagnostics::HashUtilities::deep_transform!
+    # * ::Xqsr3::HashUtilities::DeepTransform
     #
     module DeepTransform
     end # module DeepTransform
+
+    # Hash key matching
+    #
+    # === Components of interest
+    # * ::Xqsr3::HashUtilities::KeyMatching
+    #
+    module KeyMatching
+    end # module KeyMatching
   end # module HashUtilities
 
   # IO

lib/xqsr3/extensions/hash/slice.rb

@@ -2,8 +2,10 @@
 
 unless Hash.instance_methods.include? :slice
 
+  # Standard Ruby Hash extended with #slice when unavailable.
   class Hash
 
+    # Returns a new hash containing only the requested existing keys.
     def slice(*args)
 
       r = {}

lib/xqsr3/extensions/integer/to_s_grp.rb

@@ -5,7 +5,7 @@
 # Purpose:  Adds a to_s_grp() method to the Integer class
 #
 # Created:  29th March 2024
-# Updated:  19th August 2026
+# Updated:  28th August 2026
 #
 # Home:     https://github.com/synesissoftware/xqsr3
 #
@@ -47,6 +47,7 @@
 =begin
 =end
 
+# Standard Ruby Integer extended with #to_s_grp.
 class Integer
 
   # Extends +Integer+ type with the +#to_s_grp()+ method

lib/xqsr3/extensions/string/map_option_string.rb

@@ -8,8 +8,10 @@ class String
   include ::Xqsr3::CommandLineUtilities::MapOptionString
 end # class String
 
+# Standard NilClass extension for safely mapping an absent option string.
 class NilClass
 
+  # Returns nil because a nil option string cannot match a declared option.
   def map_option_string *args
 
     nil