0.39.11

.github/workflows/ruby.yml

@@ -7,7 +7,7 @@
 
 #
 # Created: 29th August 2025
-# Updated: 19th August 2026
+# Updated: 29th August 2026
 #
 
 name: Ruby
@@ -18,7 +18,6 @@ on:
       - master
       - dev
       - boilerplate
-      - bp-3
       - idiomatic
       - rc1
       - rc2
@@ -33,6 +32,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:
@@ -46,6 +65,7 @@ jobs:
 
         ruby-version:
           # - head
+          - '4.0'
           - '3.4'
           - '3.3'
           - '3.2'

.sis/script_info_lines.txt

@@ -0,0 +1,3 @@
+xqsr3 is a Ruby library of extensions for the standard Ruby and 3rd-party libraries
+Copyright (c) 2019-2026, Matthew Wilson and Synesis Information Systems
+Copyright (c) 2016-2019, Matthew Wilson and Synesis Software

CHANGES.md

@@ -1,6 +1,28 @@
 # xqsr3 - Changes <!-- omit in toc -->
 
 
+## 0.39.11 - 29th August 2026
+
+* Added a user-oriented component catalogue under **docs/components/**, covering standalone components, extensions, loading paths, API summaries, and representative usage;
+* Added task-oriented guides under **docs/guides/** for getting started, component selection, input parsing and validation, collection processing, failure handling, and output formatting;
+* Normalised legacy Markdown inline-code, checklist, table, and heading markup in **README.md**, **EXAMPLES.md**, **FAQ.md**, **TODO.md**, and the example guide;
+* Added **docs/reference/README.md** describing the generated RDoc reference, and updated the Unix and Windows RDoc helpers to exclude authored **docs/** and **examples/** content from generated output;
+* Included authored **docs/** content in the gem package while continuing to exclude generated **doc/** output;
+* Set the generated RDoc title to the **xqsr3** API reference, and excluded project boilerplate pages from the reference;
+* Expanded source-level RDoc documentation and visibility annotations for the public API, including **FrequencyMap**, **BoolParser**, **ExceptionUtilities**, **WithCause**, **ParameterChecking**, and extension classes;
+* Replaced a remaining placeholder example and legacy RDoc markup in public API comments;
+* Extended **README.md** with linked component categories and navigation to the component catalogue and user guides;
+* Added a GitHub Actions Documentation job to **.github/workflows/ruby.yml** that generates an RDoc coverage report under Ruby 3.4, and aligned its push branch triggers with the canonical set;
+* Added Ruby 4.0 to the GitHub Actions test matrix across the supported operating systems;
+* Made the RDoc coverage check fail when a documentable API entity is undocumented;
+* Added `--help` support to the Unix and Windows RDoc helpers, using project metadata from **.sis/**;
+* Made the Unix and Windows RDoc helpers runnable from any working directory, with `--pwd` selecting the caller's directory and `SIS_RDOC_DOC_DIR` controlling the generated-document directory;
+* Added documentation follow-up items to **TODO.md**;
+* Removed the **.vscode/** ignore rule from **.gitignore**;
+* Refreshed `Updated:` fields and copyright date ranges in modified library sources;
+* Bumped the library version to 0.39.11 and recorded the release in **NEWS.md**;
+
+
 ## 0.39.10 - 28th August 2026
 
 * **Gemfile.lock** is no longer tracked in the repository, completing the **0.39.9** lockfile work (`lockfile false` in **Gemfile**, **.gitignore** entry, and `spec.files` exclusion in **xqsr3.gemspec**);

EXAMPLES.md

@@ -1,9 +1,8 @@
 # xqsr3 - Examples <!-- omit in toc -->
 
-|Name|Source & Description|Summary|
-|---|---|---|
-|**count_word_frequencies**|[examples/count_word_frequencies.rb](./examples/count_word_frequencies.rb)<br/>[examples/count_word_frequencies.md](./examples/count_word_frequencies.md)|Simple example supporting ```--help``` and ```--version```|
+| Name                       | Source & Description | Summary |
+| -------------------------- | -------------------- | ------- |
+| **count_word_frequencies** | [examples/count_word_frequencies.rb](./examples/count_word_frequencies.rb)<br/>[examples/count_word_frequencies.md](./examples/count_word_frequencies.md) | Simple example supporting `--help` and `--version` |
 
 
-<!-- ########################### end of file ########################### -->
-
+<!-- ########################### end of file ########################### -->

FAQ.md

@@ -10,9 +10,6 @@ it will be used to create one.
 - [Q1: "How do I install this library?"](#q1-how-do-i-install-this-library)
 
 
-# FAQs: <!-- omit in toc -->
-
-
 ## Q1: "How do I install this library?"
 
 Install via **gem**:

NEWS.md

@@ -2,6 +2,7 @@
 
 | Date                | News Item                                                                            |
 | ------------------- | ------------------------------------------------------------------------------------ |
+| 29th August 2026    | [**xqsr3** 0.39.11](https://github.com/synesissoftware/xqsr3/releases/tag/0.39.11)   |
 | 28th August 2026    | [**xqsr3** 0.39.10](https://github.com/synesissoftware/xqsr3/releases/tag/0.39.10)   |
 | 21st August 2026    | [**xqsr3** 0.39.9](https://github.com/synesissoftware/xqsr3/releases/tag/0.39.9)     |
 | 20th August 2026    | [**xqsr3** 0.39.8](https://github.com/synesissoftware/xqsr3/releases/tag/0.39.8)     |

README.md

@@ -49,13 +49,13 @@ gem install xqsr3
 or add it to your `Gemfile`.
 
 Use is via specific APIs or groups. For example, in order to use the
-``FrequencyMap`` class you would ``require`` the source file, as in:
+`FrequencyMap` class you would `require` the source file, as in:
 
 ```Ruby
 require 'xqsr3/containers/frequency_map'
 ```
 
-Alternatively, to use all **test/unit** extensions you would ``require`` all
+Alternatively, to use _all_ **test/unit** extensions you would `require` all
 relative via the file:
 
 ```Ruby
@@ -69,34 +69,38 @@ which brings in nine extensions.
 
 **xqsr3** provides components in the following categories:
 
-* Array Utilities
-* Command-line Utilities
-* Containers
-* Conversion
-* Diagnostics
-* Hash Utilities
-* IO
-* Quality
-* String Utilities
+* [Array Utilities](./docs/components/array-utilities.md);
+* [Command-line Utilities](./docs/components/command-line-utilities.md);
+* [Containers](./docs/components/containers.md);
+* [Conversion](./docs/components/conversion.md);
+* [Diagnostics](./docs/components/diagnostics.md);
+* [Hash Utilities](./docs/components/hash-utilities.md);
+* [IO](./docs/components/io.md);
+* [Quality](./docs/components/quality.md);
+* [String Utilities](./docs/components/string-utilities.md);
 * ~~XML Utilities~~ **NOTE**: The **XML** components formerly in **xqsr3** in
    versions **0.29**-**0.30** are now contained in the separate project
    [**xqsr3-xml**](https://github.com/synesissoftware/xqsr3-xml/).
 
 and extensions to the following standard library components:
 
-* Array extensions
-* Enumerable extensions
-* Hash extensions
-* Integer extensions
-* IO extensions
-* Kernel extensions
-* String extensions
-* test/unit extensions
+* [Array extensions](./docs/components/extensions.md#array-extensions);
+* [Enumerable extensions](./docs/components/extensions.md#enumerable-extensions);
+* [Hash extensions](./docs/components/extensions.md#hash-extensions);
+* [Integer extensions](./docs/components/extensions.md#integer-extensions);
+* [IO extensions](./docs/components/extensions.md#io-extensions);
+* [Kernel extensions](./docs/components/extensions.md#kernel-extensions);
+* [String extensions](./docs/components/extensions.md#string-extensions);
+* [test/unit extensions](./docs/components/extensions.md#testunit-extensions);
+
+The complete [component catalogue](./docs/components/README.md) provides
+loading instructions and initial API summaries. The task-oriented guides are
+available under [docs/guides/](./docs/guides/README.md).
 
 
 ## Examples
 
-Examples are provided in the ```examples``` directory, along with a markdown description for each. A detailed list TOC of them is provided in [EXAMPLES.md](./EXAMPLES.md).
+Examples are provided in the `examples` directory, along with a markdown description for each. A detailed list TOC of them is provided in [EXAMPLES.md](./EXAMPLES.md).
 
 
 ## Project Information

TODO.md

@@ -3,8 +3,18 @@
 
 ## Functional improvements
 
-* [x] ~~~prepare `IO.writelines` (and related helpers) for frozen-string-literal defaults (Ruby 3.4+ warnings under `-W`)~~~;
-* [x] ~~~quiet Ruby 3.4 `test-unit` warnings for blocks passed to `assert_nil` / `assert_not_nil` in **test/unit/quality/tc_parameter_checking.rb**~~~;
+* [x] ~~~prepare `IO.writelines` (and related helpers) for frozen-string-literal defaults (Ruby 3.4+ warnings under `-W`)~~~ - ✅;
+* [x] ~~~quiet Ruby 3.4 `test-unit` warnings for blocks passed to `assert_nil` / `assert_not_nil` in **test/unit/quality/tc_parameter_checking.rb**~~~ - ✅;
+
+
+## Documentation
+
+* [x] ~~~curated component catalogue under **docs/components/**~~~ - ✅;
+* [x] ~~~task-oriented user guide under **docs/guides/**~~~ - ✅;
+* [ ] Additional example programs covering the public component categories;
+* [x] ~~~Expanded generated API reference~~~ - ✅;
+* [ ] Executable cookbook and recipe documentation;
+* [ ] Static documentation website with search and versioned references;
 
 
 ## Performance improvements
@@ -14,11 +24,11 @@
 
 ## Packaging improvements
 
-* [ ] **README.md** and **docs/*.md** introductory elements of main features;
-* [x] ~~~remove **Gemfile.lock**~~~;
-* [x] ~~~obtain a **run_all_unit_tests.sh** (from **misc-dev-scripts**) that skips `tput` when `$TERM` is unset or stdout is not a TTY (CI: `tput: No value for $TERM and no -T specified`)~~~;
-* [x] ~~~after the packaging/boilerplate/CI baseline release: bump **VERSION**, drop gemspec `required_ruby_version` `< 4` upper bound, and align **CHANGES**~~~;
-* [x] ~~~gemspec polish: `https` homepage, Rubygems `metadata` URIs, stop using `Date.today`, include **CHANGES.md** in packaged files~~~;
+* [x] ~~~**README.md** and **docs/*.md** introductory elements of main features~~~ - ✅;
+* [x] ~~~remove **Gemfile.lock**~~~ - ✅;
+* [x] ~~~obtain a **run_all_unit_tests.sh** (from **misc-dev-scripts**) that skips `tput` when `$TERM` is unset or stdout is not a TTY (CI: `tput: No value for $TERM and no -T specified`)~~~ - ✅;
+* [x] ~~~after the packaging/boilerplate/CI baseline release: bump **VERSION**, drop gemspec `required_ruby_version` `< 4` upper bound, and align **CHANGES**~~~ - ✅;
+* [x] ~~~gemspec polish: `https` homepage, Rubygems `metadata` URIs, stop using `Date.today`, include **CHANGES.md** in packaged files~~~ - ✅;
 
 
 <!-- ########################### end of file ########################### -->

docs/components/README.md

@@ -0,0 +1,61 @@
+# xqsr3 Component Catalogue <!-- omit in toc -->
+
+This catalogue is the user-oriented guide to the components provided by
+**xqsr3**. It is organised by component category rather than by Ruby source
+file.
+
+
+## Table of Contents <!-- omit in toc -->
+
+- [Using the catalogue](#using-the-catalogue)
+- [Categories](#categories)
+- [Related workflows](#related-workflows)
+
+
+## Using the catalogue
+
+Components are loaded explicitly. Each category page documents the relevant
+`require` path, public entry points, and representative usage.
+
+The catalogue documents the supported public surface. Internal files and
+implementation details are intentionally excluded.
+
+The ten category pages correspond to the public top-level component entry
+points under `lib/xqsr3/`. The `Extensions` page additionally covers the
+opt-in monkey patches, while `all_extensions.rb` is documented as its
+broad-scope loading choice.
+
+
+## Categories
+
+* [Array Utilities](./array-utilities.md);
+* [Command-line Utilities](./command-line-utilities.md);
+* [Containers](./containers.md);
+* [Conversion](./conversion.md);
+* [Diagnostics](./diagnostics.md);
+* [Extensions](./extensions.md);
+* [Hash Utilities](./hash-utilities.md);
+* [IO](./io.md);
+* [Quality](./quality.md);
+* [String Utilities](./string-utilities.md);
+
+
+## Related workflows
+
+Use the catalogue alongside the task-oriented guides:
+
+* [Choosing a Component](../guides/choosing-a-component.md) explains how to
+  select a category and loading scope;
+* [Getting Started](../guides/getting-started.md) demonstrates a minimal
+  application workflow;
+* [Parsing and Validating External Input](../guides/parsing-and-validating-input.md)
+  combines string, conversion, and quality components;
+* [Processing Collections](../guides/processing-collections.md) combines
+  containers, hash utilities, and extensions;
+* [Handling Failures](../guides/handling-failures.md) combines quality and
+  diagnostics components;
+* [Formatting and Writing Output](../guides/formatting-and-writing-output.md)
+  combines array, IO, and string utilities.
+
+
+<!-- ########################### end of file ########################### -->