xqsr3 0.39.10 → 0.39.11

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 1ce217f9cec0cb4a4a2b70759636345add271ecd29e894b755af95eb02c189df
-  data.tar.gz: 85997e37e26ac33b6d44e19d6923e476a5f0e3826381f6344c1f4f438dbb00b4
+  metadata.gz: 7be376b875d05077dcd53dc79b7a85d79f23931761ba1c765b9015f4b29a06d2
+  data.tar.gz: 7e78f40749a6a290600acf1d2695b8e45634be651dfa752fb23423d227283e6f
 SHA512:
-  metadata.gz: 7164b91b2b8d997ab35fbe261de3be3c445745c3d46a4c378583fcced4d5da7873e1bc0614b6ef2a4a5cba6c1b0f6f079b7374d9ca4794fa53bc6c353779ae64
-  data.tar.gz: a45ff408ba9fe2bd52b3733430b8390c01a9c032918a8070190abc443bdae2d20fdb13c8f1b92412e8da077b2a35458592e17930e48be9af0d88761a00a109f4
+  metadata.gz: 02ca2e98c607a51edbccb38082527fc2c9d800e6c5f632d8826296f16e114682c02b83bdf6ba5be747eaf444694a90efdeaa7cf96580d39fa1e7097148fb167a
+  data.tar.gz: f8500bc1f235ea1ef60de441641edb9b371563cb58102d923d0b482725a427cd0c115bf6366a5718e070e81fe0d52c3da827f98951c5f138413d932cc00987b8

data/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**);

data/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 ########################### -->

data/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**:

data/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)     |

data/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

data/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 ########################### -->

data/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 ########################### -->

data/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 ########################### -->

data/docs/components/command-line-utilities.md

@@ -0,0 +1,151 @@
+# xqsr3 Command-line Utilities <!-- omit in toc -->
+
+Command-line utilities support compact mapping from user-facing option text
+to stable Ruby symbols. The component is particularly useful when a command
+line accepts both long option names and declared single-letter shortcuts.
+
+
+## Table of Contents <!-- omit in toc -->
+
+- [Loading](#loading)
+- [When to use it](#when-to-use-it)
+- [MapOptionString](#mapoptionstring)
+- [Option-string grammar](#option-string-grammar)
+- [Standalone and extension forms](#standalone-and-extension-forms)
+- [Failure and matching behaviour](#failure-and-matching-behaviour)
+
+
+## Loading
+
+Load the command-line utility category:
+
+```Ruby
+require 'xqsr3/command_line_utilities'
+```
+
+Or load the component directly:
+
+```Ruby
+require 'xqsr3/command_line_utilities/map_option_string'
+```
+
+The module is defined as
+`Xqsr3::CommandLineUtilities::MapOptionString`.
+
+
+## When to use it
+
+Use `MapOptionString` when the application has a fixed set of option
+spellings and wants the result to be a symbol suitable for dispatch:
+
+```Ruby
+options = ['help', 'version', 'verbose']
+option = 'verbose'
+
+Xqsr3::CommandLineUtilities::MapOptionString
+  .map_option_string_from_string(option, options)
+# => :verbose
+```
+
+It is not a complete command-line parser. It does not consume `ARGV`, parse
+option arguments, or validate an option's value.
+
+
+## `MapOptionString`
+
+`map_option_string_from_string(string, option_strings)` returns the symbol
+corresponding to the first matching declared option. A declared option
+without shortcut syntax maps to itself:
+
+```Ruby
+require 'xqsr3/command_line_utilities/map_option_string'
+
+mapper = Xqsr3::CommandLineUtilities::MapOptionString
+declared = ['help', 'version', 'dry-run']
+
+mapper.map_option_string_from_string('help', declared)
+# => :help
+mapper.map_option_string_from_string('dry-run', declared)
+# => :dry_run
+mapper.map_option_string_from_string('unknown', declared)
+# => nil
+```
+
+The canonical option text is converted to a symbol using the String Utilities
+symbol rules. Consequently, hyphens become underscores in the returned
+symbol.
+
+
+## Option-string grammar
+
+Place each shortcut character in square brackets within its long spelling:
+
+```Ruby
+declared = ['[h]elp', '[v]ersion', '[d]ry-[r]un']
+
+mapper.map_option_string_from_string('h', declared)
+# => :help
+mapper.map_option_string_from_string('help', declared)
+# => :help
+mapper.map_option_string_from_string('dr', declared)
+# => :dry_run
+mapper.map_option_string_from_string('dry-run', declared)
+# => :dry_run
+```
+
+Every bracketed character contributes to the shortcut. Thus `[d]ry-[r]un`
+declares `dr`; the unbracketed long form remains `dry-run`. Text between
+brackets is retained in the long spelling and removed from the shortcut.
+
+Shortcut matching is exact. Partial long names and individual unbracketed
+characters do not match:
+
+```Ruby
+mapper.map_option_string_from_string('d', declared)
+# => nil
+mapper.map_option_string_from_string('dry', declared)
+# => nil
+```
+
+
+## Standalone and extension forms
+
+The standalone form is useful when the caller wants explicit dependencies:
+
+```Ruby
+Xqsr3::CommandLineUtilities::MapOptionString
+  .map_option_string_from_string('v', ['[v]ersion'])
+# => :version
+```
+
+The extension form adds `String#map_option_string`:
+
+```Ruby
+require 'xqsr3/extensions/string/map_option_string'
+
+'v'.map_option_string(['[v]ersion'])
+# => :version
+```
+
+The extension also defines `NilClass#map_option_string`, which returns `nil`.
+Other receiver types must respond to `to_str`.
+
+
+## Failure and matching behaviour
+
+An unmatched input returns `nil`; no exception is raised for an ordinary
+non-match. Matching is performed in declaration order, so duplicate or
+overlapping declarations should be avoided.
+
+The canonical option string is converted to a symbol only after a match.
+Names containing characters that the symbol converter rejects can therefore
+produce `nil` even though the option text matched.
+
+The optional `options` argument is accepted for interface compatibility but
+does not currently alter the mapping rules.
+
+For executable behavioural examples, see
+`test/unit/command_line_utilities/tc_map_option_string.rb`.
+
+
+<!-- ########################### end of file ########################### -->

data/docs/components/containers.md

@@ -0,0 +1,143 @@
+# xqsr3 Containers <!-- omit in toc -->
+
+The container components provide focused collection types for common
+counting and key-to-multiple-value use cases.
+
+Use `FrequencyMap` when each key has one numeric count. Use `MultiMap` when
+each key has an ordered collection of values. Both preserve the distinction
+between the number of keys and the number of associated items.
+
+
+## Table of Contents <!-- omit in toc -->
+
+- [Loading](#loading)
+- [Choosing a container](#choosing-a-container)
+- [FrequencyMap](#frequencymap)
+- [MultiMap](#multimap)
+- [Shared conventions](#shared-conventions)
+
+
+## Loading
+
+Load both containers through the category entry point:
+
+```Ruby
+require 'xqsr3/containers'
+```
+
+Or load only the component required by the application:
+
+```Ruby
+require 'xqsr3/containers/frequency_map'
+require 'xqsr3/containers/multi_map'
+```
+
+The classes are defined in `Xqsr3::Containers`.
+
+
+## Choosing a container
+
+* Choose `FrequencyMap` for histograms, frequency tables, and tallying;
+* Choose `MultiMap` for one-to-many relationships and grouped values;
+* Choose a regular `Hash` when neither counting nor one-to-many behaviour is
+  required.
+
+
+## `FrequencyMap`
+
+`Xqsr3::Containers::FrequencyMap` maps each element to a numeric count. It
+includes `Enumerable`, and its `count` method returns the total number of
+observations, while `size` returns the number of distinct elements.
+
+```Ruby
+require 'xqsr3/containers/frequency_map'
+
+frequencies = Xqsr3::Containers::FrequencyMap::ByElement[
+  'ruby', 'ruby', 'crystal', 'ruby',
+]
+
+frequencies['ruby']    # => 3
+frequencies['crystal'] # => 1
+frequencies['python']  # => 0
+frequencies.size       # => 2
+frequencies.count      # => 4
+```
+
+`ByElement[...]` is the convenient constructor when starting with a sequence
+of observations. `FrequencyMap[...]` also accepts a `Hash`, an array of
+`[key, count]` pairs, or an even-length key/count array.
+
+The primary mutation methods are:
+
+* `push(key, count = 1)` adds to the existing count and removes the key when
+  the resulting count is zero;
+* `store(key, count)` replaces the existing count and removes the key when
+  `count` is zero;
+* `<< key` records one observation;
+* `delete(key)` removes the key and its contribution to the total;
+* `merge` and `merge!` combine counts for duplicate keys.
+
+Counts must be integers. A push that would make an individual count negative
+raises `RangeError`; invalid count values raise `TypeError`.
+
+Useful queries include `each`, `each_by_key`, `each_by_frequency`, `fetch`,
+`has_key?`, `has_value?`, `key`, `keys`, `values`, `to_a`, and `to_h`.
+Indexing an absent key returns zero, whereas `fetch` can return a supplied
+default, invoke a block, or raise `KeyError`.
+
+
+## `MultiMap`
+
+`Xqsr3::Containers::MultiMap` maps each key to an array of values. It includes
+`Enumerable`, and its `size` is the number of keys while `count` is the total
+number of stored values.
+
+```Ruby
+require 'xqsr3/containers/multi_map'
+
+groups = Xqsr3::Containers::MultiMap.new
+groups.push :ruby, 'MRI', 'JRuby'
+groups.push :ruby, 'TruffleRuby'
+groups.push :python, 'CPython'
+
+groups[:ruby]   # => ['MRI', 'JRuby', 'TruffleRuby']
+groups[:python] # => ['CPython']
+groups.size     # => 2
+groups.count    # => 4
+```
+
+Pushing a key with no values still creates the key and associates it with an
+empty array. Indexing an absent key returns `nil`, which differs from an
+existing key whose value array is empty.
+
+The primary mutation methods are:
+
+* `push(key, *values)` appends values to the key's existing array;
+* `store(key, *values)` replaces the key's value array;
+* `delete(key)` removes all values mapped to the key;
+* `multi_merge` and `multi_merge!` concatenate values for duplicate keys;
+* `strict_merge` and `strict_merge!` replace values for duplicate keys.
+
+`MultiMap[...]` accepts a `Hash` whose values are arrays, an array of
+`[key, value, ...]` entries, or multiple such entries. `each` yields one
+`[key, value]` pair for every stored value. Use `each_unflattened` when the
+value array must be yielded as a whole.
+
+
+## Shared conventions
+
+Both containers provide `assoc`, `clear`, `delete`, `each_key`, `fetch`,
+`flatten`, `has_key?`, `keys`, `length`, `shift`, `size`, `to_a`, `to_hash`,
+and `values`-style operations. Both support `dup`, equality comparison with
+their corresponding `Hash` representation, and enumerator-returning methods
+when no block is supplied.
+
+The containers retain insertion order through their underlying Ruby hashes.
+Methods explicitly described as sorted—`FrequencyMap#each_by_key` and
+`FrequencyMap#each_by_frequency`—perform ordering work at enumeration time.
+
+For executable behavioural examples, see the unit tests in
+`test/unit/containers/`.
+
+
+<!-- ########################### end of file ########################### -->