Docs (0)

.github/workflows/ruby.yml

@@ -7,7 +7,7 @@
 
 #
 # Created: 29th August 2025
-# Updated: 19th August 2026
+# Updated: 28th August 2026
 #
 
 name: Ruby
@@ -18,7 +18,6 @@ on:
       - master
       - dev
       - boilerplate
-      - bp-3
       - idiomatic
       - rc1
       - rc2

CHANGES.md

@@ -1,6 +1,17 @@
 # xqsr3 - Changes <!-- omit in toc -->
 
 
+## 0.39.11 - 29th August 2026
+
+* Documented construct summaries in **FrequencyMap**, **ExceptionUtilities**,
+  **WithCause**, and **ParameterChecking** now terminate with periods and
+  comply with the 76-column rule;
+* 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**);

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

@@ -69,29 +69,33 @@ 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. Task-oriented guides will be
+developed separately under [docs/guides/](./docs/guides/README.md).
 
 
 ## Examples

TODO.md

@@ -7,6 +7,15 @@
 * [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
+
+* [ ] Curated component catalogue under **docs/components/**;
+* [ ] Task-oriented user guide under **docs/guides/**;
+* [ ] Expanded generated API reference;
+* [ ] Executable cookbook and recipe documentation;
+* [ ] Static documentation website with search and versioned references;
+
+
 ## Performance improvements
 
 * \<none>

docs/components/README.md

@@ -0,0 +1,37 @@
+# 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)
+
+
+## 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.
+
+
+## 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);
+
+
+<!-- ########################### end of file ########################### -->

docs/components/array-utilities.md

@@ -0,0 +1,120 @@
+# xqsr3 Array Utilities <!-- omit in toc -->
+
+Array utilities provide standalone operations for working with Ruby arrays.
+The current component is a formatter for presenting alternatives in
+human-readable text.
+
+
+## Table of Contents <!-- omit in toc -->
+
+- [Loading](#loading)
+- [When to use it](#when-to-use-it)
+- [JoinWithOr](#joinwithor)
+- [Formatting options](#formatting-options)
+- [Standalone and extension forms](#standalone-and-extension-forms)
+
+
+## Loading
+
+```Ruby
+require 'xqsr3/array_utilities'
+```
+
+Or load the component directly:
+
+```Ruby
+require 'xqsr3/array_utilities/join_with_or'
+```
+
+The standalone module is
+`Xqsr3::ArrayUtilities::JoinWithOr`.
+
+
+## When to use it
+
+Use `join_with_or` for messages that describe alternatives, such as accepted
+formats, permitted values, or choices presented to a user. It is not a
+general-purpose serialization method: it adds grammatical spacing and an
+optional Oxford comma.
+
+
+## `JoinWithOr`
+
+`Xqsr3::ArrayUtilities::JoinWithOr.join_with_or` formats values using these
+cardinality rules:
+
+* `nil` and an empty array produce `''`;
+* one value produces that value;
+* two values are joined with `or` and no comma;
+* three or more values use commas and, by default, an Oxford comma before
+  `or`.
+
+```Ruby
+require 'xqsr3/array_utilities/join_with_or'
+
+formatter = Xqsr3::ArrayUtilities::JoinWithOr
+
+formatter.join_with_or([])
+# => ''
+formatter.join_with_or(['red'])
+# => 'red'
+formatter.join_with_or(['red', 'green'])
+# => 'red or green'
+formatter.join_with_or(['red', 'green', 'blue'])
+# => 'red, green, or blue'
+```
+
+Values are interpolated into the result, so they do not need to be strings.
+The array argument itself must be an `Array` or `nil`; another type raises
+`TypeError`.
+
+
+## Formatting options
+
+The `or` word, separator, Oxford-comma policy, and quote character are
+independent options:
+
+```Ruby
+formatter.join_with_or(
+  ['red', 'green', 'blue'],
+  or: 'OR',
+  separator: ';',
+  oxford_comma: false,
+  quote_char: '"',
+)
+# => '"red"; "green" OR "blue"'
+```
+
+The options are:
+
+* `or` replaces the default word `or`;
+* `separator` replaces the default comma between items;
+* `oxford_comma: false` removes the separator before `or` for lists of three
+  or more values;
+* `quote_char` surrounds every value with the supplied character.
+
+The Oxford-comma option has no effect for zero, one, or two values. A
+`quote_char` is applied literally to both sides and does not escape quote
+characters already present in a value.
+
+
+## Standalone and extension forms
+
+The extension form adds `Array#join_with_or`:
+
+```Ruby
+require 'xqsr3/extensions/array/join_with_or'
+
+['red', 'green', 'blue'].join_with_or
+# => 'red, green, or blue'
+```
+
+The extension delegates to the standalone implementation. Use the standalone
+form in reusable libraries that want to avoid modifying `Array`; use the
+extension form when method syntax improves the surrounding application code.
+
+For executable behavioural examples, see
+`test/unit/array_utilities/tc_join_with_or.rb`.
+
+
+<!-- ########################### end of file ########################### -->