Skip to content

Docs (1) - #33

Merged
synesissoftware merged 24 commits into
synesissoftware:devfrom
mwsis:doc.1
Aug 29, 2026
Merged

Docs (1)#33
synesissoftware merged 24 commits into
synesissoftware:devfrom
mwsis:doc.1

Conversation

@mwsis

@mwsis mwsis commented Aug 28, 2026

Copy link
Copy Markdown
Collaborator

No description provided.

mwsis added 22 commits August 28, 2026 17:03
@mwsis
squash-commit
c18de99
@mwsis
chore(doc): update documentation metadata for 0.39.11
b08f3e5
@mwsis
chore(doc): establish component documentation structure
431b69c 
* add the initial component catalogue under docs/components/;
* reserve docs/guides/ for task-oriented documentation;
* link component documentation from README.md;
* record the documentation roadmap in TODO.md;
@mwsis
docs(components): document container selection and behaviour
7815cae 
* replace the generic Containers summary with substantive usage guidance;
* explain when to choose FrequencyMap, MultiMap, or Hash;
* document category-level and component-level loading;
* describe FrequencyMap counting, construction, mutation, querying, and
  errors;
* describe MultiMap cardinality, construction, mutation, enumeration, and
  merge semantics;
* document absent-key, empty-value, ordering, and conversion behaviour;
* link the catalogue to the container unit tests;
@mwsis
docs(components): document scalar conversion policies
de4d4cd 
* explain when to use BoolParser and IntegerParser at input boundaries;
* document strict boolean matching, custom matchers, aliases, and
  fallbacks;
* document integer bases, native exceptions, defaults, nil handling, and
  recovery blocks;
* clarify the distinction between conversion and validation;
* verify the documented conversion examples against the implementation;
@mwsis
docs(components): document string transformation and matching semantics
7008f9f 
* explain prefix and suffix matching return values and edge cases;
* distinguish empty-string and whitespace-only normalization;
* document conditional quoting triggers and quote configuration;
* document symbol conversion, character transformation, and rejection
  policies;
* document truncation width and omission behaviour;
* clarify standalone utility and String extension loading;
* link behavioural documentation to the relevant unit tests;
@mwsis
docs(components): document diagnostic context and exception chaining
553ee44 
* explain when to use option-aware raising, inspection building, and
  causes;
* document ExceptionUtilities constructor options and raise compatibility;
* document InspectBuilder field selection, truncation, and hidden-field
  policies;
* document WithCause construction, chaining, traversal, and message
  separators;
* clarify application-level versus interpreter-managed exception causes;
* add guidance for avoiding sensitive diagnostic output;
* verify examples against the diagnostics unit tests;
@mwsis
docs(components): document Ruby extension loading and semantics
a02fedb 
* explain narrow, grouped, standard, and test-inclusive loading scopes;
* document global core-class modification and reusable-library trade-offs;
* describe Enumerable extension semantics and block contracts;
* document Hash extension mutation and Ruby-version compatibility
  behaviour;
* document Integer, IO, Kernel, String, and test/unit extensions;
* correct examples for IO.writelines and Integer#to_s_grp;
* verify extension examples against 119 unit tests and 390 assertions;
@mwsis
docs(components): document hash transformation and matching semantics
cc0a451 
* explain standalone and extension loading choices;
* document deep transformation block arities and recursion boundaries;
* distinguish copy and in-place transformation safety;
* document exact-key precedence and regular-expression matching;
* explain match versus has_match? results and nil ambiguity;
* document regex-key handling and iteration-order effects;
* verify examples against the hash utility unit tests;
@mwsis
docs(components): document parameter and option validation
387b927 
* explain boundary-checking patterns for public APIs;
* document type, shape, capability, value, and emptiness checks;
* describe case-insensitive and order-insensitive comparisons;
* document custom validation blocks and failure classification;
* explain option aliases and missing-option handling;
* document nothrow, custom messages, and obsolete compatibility aliases;
* verify examples against the quality unit tests;
@mwsis
docs(components): document human-readable array formatting
12dd71b 
* explain when join_with_or is appropriate;
* document cardinality-specific formatting behaviour;
* document conjunction, separator, Oxford-comma, and quote options;
* explain standalone and Array extension loading;
* document type and quoting caveats;
* verify examples against the array utility unit tests;
@mwsis
docs(components): document command-line option mapping
61e7c87 
* distinguish option mapping from complete command-line parsing;
* document long-option and shortcut matching semantics;
* explain bracketed shortcut declaration grammar;
* document canonical symbol conversion behaviour;
* explain standalone and String extension forms;
* document nil, unmatched, ordering, and failure behaviour;
* verify examples against the command-line unit tests;
@mwsis
docs(components): document structured IO writing
b4c4468 
* explain path and writable-stream target behaviour;
* document string, array, and hash input forms;
* describe line and column separator options;
* document line-ending deduction and lookahead limits;
* explain final-EOL suppression and return values;
* clarify standalone and IO extension loading;
* verify examples against the IO unit tests;
@mwsis
docs(guides): add the xqsr3 getting-started workflow
ba01eae 
* document gem and Bundler installation;
* explain explicit category and component loading;
* demonstrate frequency collection with FrequencyMap;
* demonstrate boundary conversion and parameter validation;
* demonstrate structured output with IO.writelines;
* link the guide to the component catalogue;
* verify the documented workflow against the library;
@mwsis
docs(guides): add component selection guidance
a356bab 
* explain selection by data shape and desired operation;
* distinguish standalone and globally modifying extension APIs;
* document narrow and broad require scopes;
* demonstrate conversion, validation, storage, and output composition;
* identify common component mismatches and failure modes;
* link the guide to the detailed component catalogue;
* verify the composed workflow against the library;
@mwsis
docs(guides): document external input processing
f280a9d 
* separate normalization, conversion, validation, and storage;
* document blank-value handling and explicit text normalization;
* demonstrate Boolean and integer conversion policies;
* document domain validation and failure strategies;
* explain raising, fallback, non-throwing, and recovery modes;
* provide a complete normalized-configuration workflow;
* verify the composed workflow against the library;
@mwsis
docs(reference): establish the generated API reference
cddffd7 
* complete the RDoc namespace index for core components;
* add missing Containers and Conversion cross-references;
* correct Hash Utilities namespace documentation;
* document generated doc/ output and the RDoc workflow;
* distinguish authored guides from generated API reference material;
* verify RDoc generation and document its coverage result;
@mwsis
docs(reference): complete generated API documentation coverage
77bf014 
* document the Integer extension class;
* document the compatibility Hash#slice method;
* document NilClass#map_option_string;
* exclude authored guides and examples from API extraction;
* update RDoc generation metadata;
* achieve complete coverage across 197 API entities;
@mwsis
ci(docs): verify generated API reference coverage
9411181 
* add a dedicated documentation workflow job;
* run RDoc coverage under Ruby 3.4 on Ubuntu;
* fail CI when undocumented API entities are introduced;
* preserve the existing test and warning jobs;
* validate the workflow YAML locally;
@mwsis
docs(reference): exclude the private BoolParser helper
4c5ce26 
* mark the private matches_to_ helper as no-doc;
* remove implementation-detail prose from the API documentation;
* preserve the helper as an internal conversion detail;
* restore complete RDoc coverage at 100 percent;
* verify all 197 documentable API entities;
@mwsis
docs(xqsr3): complete task-oriented workflow documentation
233a2f2 
- add collection processing workflow guidance;
- add failure handling and diagnostic workflow guidance;
- add formatting and output writing workflow guidance;
- update the guide index and mark Option 2 complete;
- update the documentation roadmap status;
@mwsis
docs(xqsr3): complete curated component catalogue
d26271d 
- confirm coverage of all ten public component categories;
- explain standalone, extension, and broad-scope loading choices;
- cross-link catalogue entries to task-oriented workflows;
- mark the curated component catalogue complete;
@mwsis
mwsis requested a review from synesissoftware August 28, 2026 12:28
@mwsis mwsis self-assigned this Aug 28, 2026
@mwsis
mwsis changed the base branch from master to dev August 29, 2026 04:16
@synesissoftware
synesissoftware merged commit b299e06 into synesissoftware:dev Aug 29, 2026
27 checks passed
@mwsis
mwsis deleted the doc.1 branch August 29, 2026 04:30
synesissoftware added a commit that referenced this pull request Aug 29, 2026
@synesissoftware @mwsis
0.39.11 (#34)
50f48ae 
* Docs (0) (#30)

* squash-commit

* chore(doc): update documentation metadata for 0.39.11

* chore(doc): establish component documentation structure

* add the initial component catalogue under docs/components/;
* reserve docs/guides/ for task-oriented documentation;
* link component documentation from README.md;
* record the documentation roadmap in TODO.md;

* docs(components): document container selection and behaviour

* replace the generic Containers summary with substantive usage guidance;
* explain when to choose FrequencyMap, MultiMap, or Hash;
* document category-level and component-level loading;
* describe FrequencyMap counting, construction, mutation, querying, and
  errors;
* describe MultiMap cardinality, construction, mutation, enumeration, and
  merge semantics;
* document absent-key, empty-value, ordering, and conversion behaviour;
* link the catalogue to the container unit tests;

* docs(components): document scalar conversion policies

* explain when to use BoolParser and IntegerParser at input boundaries;
* document strict boolean matching, custom matchers, aliases, and
  fallbacks;
* document integer bases, native exceptions, defaults, nil handling, and
  recovery blocks;
* clarify the distinction between conversion and validation;
* verify the documented conversion examples against the implementation;

* docs(components): document string transformation and matching semantics

* explain prefix and suffix matching return values and edge cases;
* distinguish empty-string and whitespace-only normalization;
* document conditional quoting triggers and quote configuration;
* document symbol conversion, character transformation, and rejection
  policies;
* document truncation width and omission behaviour;
* clarify standalone utility and String extension loading;
* link behavioural documentation to the relevant unit tests;

* docs(components): document diagnostic context and exception chaining

* explain when to use option-aware raising, inspection building, and
  causes;
* document ExceptionUtilities constructor options and raise compatibility;
* document InspectBuilder field selection, truncation, and hidden-field
  policies;
* document WithCause construction, chaining, traversal, and message
  separators;
* clarify application-level versus interpreter-managed exception causes;
* add guidance for avoiding sensitive diagnostic output;
* verify examples against the diagnostics unit tests;

* docs(components): document Ruby extension loading and semantics

* explain narrow, grouped, standard, and test-inclusive loading scopes;
* document global core-class modification and reusable-library trade-offs;
* describe Enumerable extension semantics and block contracts;
* document Hash extension mutation and Ruby-version compatibility
  behaviour;
* document Integer, IO, Kernel, String, and test/unit extensions;
* correct examples for IO.writelines and Integer#to_s_grp;
* verify extension examples against 119 unit tests and 390 assertions;

* docs(components): document hash transformation and matching semantics

* explain standalone and extension loading choices;
* document deep transformation block arities and recursion boundaries;
* distinguish copy and in-place transformation safety;
* document exact-key precedence and regular-expression matching;
* explain match versus has_match? results and nil ambiguity;
* document regex-key handling and iteration-order effects;
* verify examples against the hash utility unit tests;

* docs(components): document parameter and option validation

* explain boundary-checking patterns for public APIs;
* document type, shape, capability, value, and emptiness checks;
* describe case-insensitive and order-insensitive comparisons;
* document custom validation blocks and failure classification;
* explain option aliases and missing-option handling;
* document nothrow, custom messages, and obsolete compatibility aliases;
* verify examples against the quality unit tests;

* docs(components): document human-readable array formatting

* explain when join_with_or is appropriate;
* document cardinality-specific formatting behaviour;
* document conjunction, separator, Oxford-comma, and quote options;
* explain standalone and Array extension loading;
* document type and quoting caveats;
* verify examples against the array utility unit tests;

* docs(components): document command-line option mapping

* distinguish option mapping from complete command-line parsing;
* document long-option and shortcut matching semantics;
* explain bracketed shortcut declaration grammar;
* document canonical symbol conversion behaviour;
* explain standalone and String extension forms;
* document nil, unmatched, ordering, and failure behaviour;
* verify examples against the command-line unit tests;

* docs(components): document structured IO writing

* explain path and writable-stream target behaviour;
* document string, array, and hash input forms;
* describe line and column separator options;
* document line-ending deduction and lookahead limits;
* explain final-EOL suppression and return values;
* clarify standalone and IO extension loading;
* verify examples against the IO unit tests;

* docs(guides): add the xqsr3 getting-started workflow

* document gem and Bundler installation;
* explain explicit category and component loading;
* demonstrate frequency collection with FrequencyMap;
* demonstrate boundary conversion and parameter validation;
* demonstrate structured output with IO.writelines;
* link the guide to the component catalogue;
* verify the documented workflow against the library;

* docs(guides): add component selection guidance

* explain selection by data shape and desired operation;
* distinguish standalone and globally modifying extension APIs;
* document narrow and broad require scopes;
* demonstrate conversion, validation, storage, and output composition;
* identify common component mismatches and failure modes;
* link the guide to the detailed component catalogue;
* verify the composed workflow against the library;

* docs(guides): document external input processing

* separate normalization, conversion, validation, and storage;
* document blank-value handling and explicit text normalization;
* demonstrate Boolean and integer conversion policies;
* document domain validation and failure strategies;
* explain raising, fallback, non-throwing, and recovery modes;
* provide a complete normalized-configuration workflow;
* verify the composed workflow against the library;

* Boilerplate (#29)

* chore(ci): tidying

* chore(gemspec): wire gemspec URLs through PROJECT_URL

* Docs (3) (#31)

* squash-commit

* chore(doc): update documentation metadata for 0.39.11

* chore(doc): establish component documentation structure

* add the initial component catalogue under docs/components/;
* reserve docs/guides/ for task-oriented documentation;
* link component documentation from README.md;
* record the documentation roadmap in TODO.md;

* docs(components): document container selection and behaviour

* replace the generic Containers summary with substantive usage guidance;
* explain when to choose FrequencyMap, MultiMap, or Hash;
* document category-level and component-level loading;
* describe FrequencyMap counting, construction, mutation, querying, and
  errors;
* describe MultiMap cardinality, construction, mutation, enumeration, and
  merge semantics;
* document absent-key, empty-value, ordering, and conversion behaviour;
* link the catalogue to the container unit tests;

* docs(components): document scalar conversion policies

* explain when to use BoolParser and IntegerParser at input boundaries;
* document strict boolean matching, custom matchers, aliases, and
  fallbacks;
* document integer bases, native exceptions, defaults, nil handling, and
  recovery blocks;
* clarify the distinction between conversion and validation;
* verify the documented conversion examples against the implementation;

* docs(components): document string transformation and matching semantics

* explain prefix and suffix matching return values and edge cases;
* distinguish empty-string and whitespace-only normalization;
* document conditional quoting triggers and quote configuration;
* document symbol conversion, character transformation, and rejection
  policies;
* document truncation width and omission behaviour;
* clarify standalone utility and String extension loading;
* link behavioural documentation to the relevant unit tests;

* docs(components): document diagnostic context and exception chaining

* explain when to use option-aware raising, inspection building, and
  causes;
* document ExceptionUtilities constructor options and raise compatibility;
* document InspectBuilder field selection, truncation, and hidden-field
  policies;
* document WithCause construction, chaining, traversal, and message
  separators;
* clarify application-level versus interpreter-managed exception causes;
* add guidance for avoiding sensitive diagnostic output;
* verify examples against the diagnostics unit tests;

* docs(components): document Ruby extension loading and semantics

* explain narrow, grouped, standard, and test-inclusive loading scopes;
* document global core-class modification and reusable-library trade-offs;
* describe Enumerable extension semantics and block contracts;
* document Hash extension mutation and Ruby-version compatibility
  behaviour;
* document Integer, IO, Kernel, String, and test/unit extensions;
* correct examples for IO.writelines and Integer#to_s_grp;
* verify extension examples against 119 unit tests and 390 assertions;

* docs(components): document hash transformation and matching semantics

* explain standalone and extension loading choices;
* document deep transformation block arities and recursion boundaries;
* distinguish copy and in-place transformation safety;
* document exact-key precedence and regular-expression matching;
* explain match versus has_match? results and nil ambiguity;
* document regex-key handling and iteration-order effects;
* verify examples against the hash utility unit tests;

* docs(components): document parameter and option validation

* explain boundary-checking patterns for public APIs;
* document type, shape, capability, value, and emptiness checks;
* describe case-insensitive and order-insensitive comparisons;
* document custom validation blocks and failure classification;
* explain option aliases and missing-option handling;
* document nothrow, custom messages, and obsolete compatibility aliases;
* verify examples against the quality unit tests;

* docs(components): document human-readable array formatting

* explain when join_with_or is appropriate;
* document cardinality-specific formatting behaviour;
* document conjunction, separator, Oxford-comma, and quote options;
* explain standalone and Array extension loading;
* document type and quoting caveats;
* verify examples against the array utility unit tests;

* docs(components): document command-line option mapping

* distinguish option mapping from complete command-line parsing;
* document long-option and shortcut matching semantics;
* explain bracketed shortcut declaration grammar;
* document canonical symbol conversion behaviour;
* explain standalone and String extension forms;
* document nil, unmatched, ordering, and failure behaviour;
* verify examples against the command-line unit tests;

* docs(components): document structured IO writing

* explain path and writable-stream target behaviour;
* document string, array, and hash input forms;
* describe line and column separator options;
* document line-ending deduction and lookahead limits;
* explain final-EOL suppression and return values;
* clarify standalone and IO extension loading;
* verify examples against the IO unit tests;

* docs(guides): add the xqsr3 getting-started workflow

* document gem and Bundler installation;
* explain explicit category and component loading;
* demonstrate frequency collection with FrequencyMap;
* demonstrate boundary conversion and parameter validation;
* demonstrate structured output with IO.writelines;
* link the guide to the component catalogue;
* verify the documented workflow against the library;

* docs(guides): add component selection guidance

* explain selection by data shape and desired operation;
* distinguish standalone and globally modifying extension APIs;
* document narrow and broad require scopes;
* demonstrate conversion, validation, storage, and output composition;
* identify common component mismatches and failure modes;
* link the guide to the detailed component catalogue;
* verify the composed workflow against the library;

* docs(guides): document external input processing

* separate normalization, conversion, validation, and storage;
* document blank-value handling and explicit text normalization;
* demonstrate Boolean and integer conversion policies;
* document domain validation and failure strategies;
* explain raising, fallback, non-throwing, and recovery modes;
* provide a complete normalized-configuration workflow;
* verify the composed workflow against the library;

* docs(reference): establish the generated API reference

* complete the RDoc namespace index for core components;
* add missing Containers and Conversion cross-references;
* correct Hash Utilities namespace documentation;
* document generated doc/ output and the RDoc workflow;
* distinguish authored guides from generated API reference material;
* verify RDoc generation and document its coverage result;

* docs(reference): complete generated API documentation coverage

* document the Integer extension class;
* document the compatibility Hash#slice method;
* document NilClass#map_option_string;
* exclude authored guides and examples from API extraction;
* update RDoc generation metadata;
* achieve complete coverage across 197 API entities;

* ci(docs): verify generated API reference coverage

* add a dedicated documentation workflow job;
* run RDoc coverage under Ruby 3.4 on Ubuntu;
* fail CI when undocumented API entities are introduced;
* preserve the existing test and warning jobs;
* validate the workflow YAML locally;

* docs(reference): exclude the private BoolParser helper

* mark the private matches_to_ helper as no-doc;
* remove implementation-detail prose from the API documentation;
* preserve the helper as an internal conversion detail;
* restore complete RDoc coverage at 100 percent;
* verify all 197 documentable API entities;

* Docs (2) (#32)

* squash-commit

* chore(doc): update documentation metadata for 0.39.11

* chore(doc): establish component documentation structure

* add the initial component catalogue under docs/components/;
* reserve docs/guides/ for task-oriented documentation;
* link component documentation from README.md;
* record the documentation roadmap in TODO.md;

* docs(components): document container selection and behaviour

* replace the generic Containers summary with substantive usage guidance;
* explain when to choose FrequencyMap, MultiMap, or Hash;
* document category-level and component-level loading;
* describe FrequencyMap counting, construction, mutation, querying, and
  errors;
* describe MultiMap cardinality, construction, mutation, enumeration, and
  merge semantics;
* document absent-key, empty-value, ordering, and conversion behaviour;
* link the catalogue to the container unit tests;

* docs(components): document scalar conversion policies

* explain when to use BoolParser and IntegerParser at input boundaries;
* document strict boolean matching, custom matchers, aliases, and
  fallbacks;
* document integer bases, native exceptions, defaults, nil handling, and
  recovery blocks;
* clarify the distinction between conversion and validation;
* verify the documented conversion examples against the implementation;

* docs(components): document string transformation and matching semantics

* explain prefix and suffix matching return values and edge cases;
* distinguish empty-string and whitespace-only normalization;
* document conditional quoting triggers and quote configuration;
* document symbol conversion, character transformation, and rejection
  policies;
* document truncation width and omission behaviour;
* clarify standalone utility and String extension loading;
* link behavioural documentation to the relevant unit tests;

* docs(components): document diagnostic context and exception chaining

* explain when to use option-aware raising, inspection building, and
  causes;
* document ExceptionUtilities constructor options and raise compatibility;
* document InspectBuilder field selection, truncation, and hidden-field
  policies;
* document WithCause construction, chaining, traversal, and message
  separators;
* clarify application-level versus interpreter-managed exception causes;
* add guidance for avoiding sensitive diagnostic output;
* verify examples against the diagnostics unit tests;

* docs(components): document Ruby extension loading and semantics

* explain narrow, grouped, standard, and test-inclusive loading scopes;
* document global core-class modification and reusable-library trade-offs;
* describe Enumerable extension semantics and block contracts;
* document Hash extension mutation and Ruby-version compatibility
  behaviour;
* document Integer, IO, Kernel, String, and test/unit extensions;
* correct examples for IO.writelines and Integer#to_s_grp;
* verify extension examples against 119 unit tests and 390 assertions;

* docs(components): document hash transformation and matching semantics

* explain standalone and extension loading choices;
* document deep transformation block arities and recursion boundaries;
* distinguish copy and in-place transformation safety;
* document exact-key precedence and regular-expression matching;
* explain match versus has_match? results and nil ambiguity;
* document regex-key handling and iteration-order effects;
* verify examples against the hash utility unit tests;

* docs(components): document parameter and option validation

* explain boundary-checking patterns for public APIs;
* document type, shape, capability, value, and emptiness checks;
* describe case-insensitive and order-insensitive comparisons;
* document custom validation blocks and failure classification;
* explain option aliases and missing-option handling;
* document nothrow, custom messages, and obsolete compatibility aliases;
* verify examples against the quality unit tests;

* docs(components): document human-readable array formatting

* explain when join_with_or is appropriate;
* document cardinality-specific formatting behaviour;
* document conjunction, separator, Oxford-comma, and quote options;
* explain standalone and Array extension loading;
* document type and quoting caveats;
* verify examples against the array utility unit tests;

* docs(components): document command-line option mapping

* distinguish option mapping from complete command-line parsing;
* document long-option and shortcut matching semantics;
* explain bracketed shortcut declaration grammar;
* document canonical symbol conversion behaviour;
* explain standalone and String extension forms;
* document nil, unmatched, ordering, and failure behaviour;
* verify examples against the command-line unit tests;

* docs(components): document structured IO writing

* explain path and writable-stream target behaviour;
* document string, array, and hash input forms;
* describe line and column separator options;
* document line-ending deduction and lookahead limits;
* explain final-EOL suppression and return values;
* clarify standalone and IO extension loading;
* verify examples against the IO unit tests;

* docs(guides): add the xqsr3 getting-started workflow

* document gem and Bundler installation;
* explain explicit category and component loading;
* demonstrate frequency collection with FrequencyMap;
* demonstrate boundary conversion and parameter validation;
* demonstrate structured output with IO.writelines;
* link the guide to the component catalogue;
* verify the documented workflow against the library;

* docs(guides): add component selection guidance

* explain selection by data shape and desired operation;
* distinguish standalone and globally modifying extension APIs;
* document narrow and broad require scopes;
* demonstrate conversion, validation, storage, and output composition;
* identify common component mismatches and failure modes;
* link the guide to the detailed component catalogue;
* verify the composed workflow against the library;

* docs(guides): document external input processing

* separate normalization, conversion, validation, and storage;
* document blank-value handling and explicit text normalization;
* demonstrate Boolean and integer conversion policies;
* document domain validation and failure strategies;
* explain raising, fallback, non-throwing, and recovery modes;
* provide a complete normalized-configuration workflow;
* verify the composed workflow against the library;

* docs(reference): establish the generated API reference

* complete the RDoc namespace index for core components;
* add missing Containers and Conversion cross-references;
* correct Hash Utilities namespace documentation;
* document generated doc/ output and the RDoc workflow;
* distinguish authored guides from generated API reference material;
* verify RDoc generation and document its coverage result;

* docs(reference): complete generated API documentation coverage

* document the Integer extension class;
* document the compatibility Hash#slice method;
* document NilClass#map_option_string;
* exclude authored guides and examples from API extraction;
* update RDoc generation metadata;
* achieve complete coverage across 197 API entities;

* ci(docs): verify generated API reference coverage

* add a dedicated documentation workflow job;
* run RDoc coverage under Ruby 3.4 on Ubuntu;
* fail CI when undocumented API entities are introduced;
* preserve the existing test and warning jobs;
* validate the workflow YAML locally;

* docs(reference): exclude the private BoolParser helper

* mark the private matches_to_ helper as no-doc;
* remove implementation-detail prose from the API documentation;
* preserve the helper as an internal conversion detail;
* restore complete RDoc coverage at 100 percent;
* verify all 197 documentable API entities;

* docs(xqsr3): complete task-oriented workflow documentation

- add collection processing workflow guidance;
- add failure handling and diagnostic workflow guidance;
- add formatting and output writing workflow guidance;
- update the guide index and mark Option 2 complete;
- update the documentation roadmap status;

* empty

* Docs (1) (#33)

* squash-commit

* chore(doc): update documentation metadata for 0.39.11

* chore(doc): establish component documentation structure

* add the initial component catalogue under docs/components/;
* reserve docs/guides/ for task-oriented documentation;
* link component documentation from README.md;
* record the documentation roadmap in TODO.md;

* docs(components): document container selection and behaviour

* replace the generic Containers summary with substantive usage guidance;
* explain when to choose FrequencyMap, MultiMap, or Hash;
* document category-level and component-level loading;
* describe FrequencyMap counting, construction, mutation, querying, and
  errors;
* describe MultiMap cardinality, construction, mutation, enumeration, and
  merge semantics;
* document absent-key, empty-value, ordering, and conversion behaviour;
* link the catalogue to the container unit tests;

* docs(components): document scalar conversion policies

* explain when to use BoolParser and IntegerParser at input boundaries;
* document strict boolean matching, custom matchers, aliases, and
  fallbacks;
* document integer bases, native exceptions, defaults, nil handling, and
  recovery blocks;
* clarify the distinction between conversion and validation;
* verify the documented conversion examples against the implementation;

* docs(components): document string transformation and matching semantics

* explain prefix and suffix matching return values and edge cases;
* distinguish empty-string and whitespace-only normalization;
* document conditional quoting triggers and quote configuration;
* document symbol conversion, character transformation, and rejection
  policies;
* document truncation width and omission behaviour;
* clarify standalone utility and String extension loading;
* link behavioural documentation to the relevant unit tests;

* docs(components): document diagnostic context and exception chaining

* explain when to use option-aware raising, inspection building, and
  causes;
* document ExceptionUtilities constructor options and raise compatibility;
* document InspectBuilder field selection, truncation, and hidden-field
  policies;
* document WithCause construction, chaining, traversal, and message
  separators;
* clarify application-level versus interpreter-managed exception causes;
* add guidance for avoiding sensitive diagnostic output;
* verify examples against the diagnostics unit tests;

* docs(components): document Ruby extension loading and semantics

* explain narrow, grouped, standard, and test-inclusive loading scopes;
* document global core-class modification and reusable-library trade-offs;
* describe Enumerable extension semantics and block contracts;
* document Hash extension mutation and Ruby-version compatibility
  behaviour;
* document Integer, IO, Kernel, String, and test/unit extensions;
* correct examples for IO.writelines and Integer#to_s_grp;
* verify extension examples against 119 unit tests and 390 assertions;

* docs(components): document hash transformation and matching semantics

* explain standalone and extension loading choices;
* document deep transformation block arities and recursion boundaries;
* distinguish copy and in-place transformation safety;
* document exact-key precedence and regular-expression matching;
* explain match versus has_match? results and nil ambiguity;
* document regex-key handling and iteration-order effects;
* verify examples against the hash utility unit tests;

* docs(components): document parameter and option validation

* explain boundary-checking patterns for public APIs;
* document type, shape, capability, value, and emptiness checks;
* describe case-insensitive and order-insensitive comparisons;
* document custom validation blocks and failure classification;
* explain option aliases and missing-option handling;
* document nothrow, custom messages, and obsolete compatibility aliases;
* verify examples against the quality unit tests;

* docs(components): document human-readable array formatting

* explain when join_with_or is appropriate;
* document cardinality-specific formatting behaviour;
* document conjunction, separator, Oxford-comma, and quote options;
* explain standalone and Array extension loading;
* document type and quoting caveats;
* verify examples against the array utility unit tests;

* docs(components): document command-line option mapping

* distinguish option mapping from complete command-line parsing;
* document long-option and shortcut matching semantics;
* explain bracketed shortcut declaration grammar;
* document canonical symbol conversion behaviour;
* explain standalone and String extension forms;
* document nil, unmatched, ordering, and failure behaviour;
* verify examples against the command-line unit tests;

* docs(components): document structured IO writing

* explain path and writable-stream target behaviour;
* document string, array, and hash input forms;
* describe line and column separator options;
* document line-ending deduction and lookahead limits;
* explain final-EOL suppression and return values;
* clarify standalone and IO extension loading;
* verify examples against the IO unit tests;

* docs(guides): add the xqsr3 getting-started workflow

* document gem and Bundler installation;
* explain explicit category and component loading;
* demonstrate frequency collection with FrequencyMap;
* demonstrate boundary conversion and parameter validation;
* demonstrate structured output with IO.writelines;
* link the guide to the component catalogue;
* verify the documented workflow against the library;

* docs(guides): add component selection guidance

* explain selection by data shape and desired operation;
* distinguish standalone and globally modifying extension APIs;
* document narrow and broad require scopes;
* demonstrate conversion, validation, storage, and output composition;
* identify common component mismatches and failure modes;
* link the guide to the detailed component catalogue;
* verify the composed workflow against the library;

* docs(guides): document external input processing

* separate normalization, conversion, validation, and storage;
* document blank-value handling and explicit text normalization;
* demonstrate Boolean and integer conversion policies;
* document domain validation and failure strategies;
* explain raising, fallback, non-throwing, and recovery modes;
* provide a complete normalized-configuration workflow;
* verify the composed workflow against the library;

* docs(reference): establish the generated API reference

* complete the RDoc namespace index for core components;
* add missing Containers and Conversion cross-references;
* correct Hash Utilities namespace documentation;
* document generated doc/ output and the RDoc workflow;
* distinguish authored guides from generated API reference material;
* verify RDoc generation and document its coverage result;

* docs(reference): complete generated API documentation coverage

* document the Integer extension class;
* document the compatibility Hash#slice method;
* document NilClass#map_option_string;
* exclude authored guides and examples from API extraction;
* update RDoc generation metadata;
* achieve complete coverage across 197 API entities;

* ci(docs): verify generated API reference coverage

* add a dedicated documentation workflow job;
* run RDoc coverage under Ruby 3.4 on Ubuntu;
* fail CI when undocumented API entities are introduced;
* preserve the existing test and warning jobs;
* validate the workflow YAML locally;

* docs(reference): exclude the private BoolParser helper

* mark the private matches_to_ helper as no-doc;
* remove implementation-detail prose from the API documentation;
* preserve the helper as an internal conversion detail;
* restore complete RDoc coverage at 100 percent;
* verify all 197 documentable API entities;

* docs(xqsr3): complete task-oriented workflow documentation

- add collection processing workflow guidance;
- add failure handling and diagnostic workflow guidance;
- add formatting and output writing workflow guidance;
- update the guide index and mark Option 2 complete;
- update the documentation roadmap status;

* docs(xqsr3): complete curated component catalogue

- confirm coverage of all ten public component categories;
- explain standalone, extension, and broad-scope loading choices;
- cross-link catalogue entries to task-oriented workflows;
- mark the curated component catalogue complete;

* squash-commit

* 0.39.11

* CI triggers now canonical

* fix: copyright / updated

* Docs: align Windows RDoc generation with Unix helper

* Exclude authored docs and examples from Windows RDoc output;
* Refresh generate_rdoc.cmd metadata for 29th August 2026;

* CI/docs: add Ruby 4.0 coverage and update release notes

* Exercise Ruby 4.0 across the supported operating-system matrix;
* Record the expanded coverage and canonical CI trigger state in
  CHANGES.md;

* RDoc: modernise metadata-aware helpers

* Add `.sis/script_info_lines.txt` for shared project help metadata;
* Make Unix and Windows helpers support `--help` and project-aware usage;
* Run helpers from their own directory by default, with `--pwd` override;
* Support `SIS_RDOC_DOC_DIR` for configurable generated documentation;
* Enforce complete RDoc coverage reports in the Unix helper;
* Record helper behaviour and coverage policy in release notes;

* Docs: correct task-guide availability status

* Update README.md to link the available task-oriented guides;
* Remove the stale statement that the guides are forthcoming;

* Docs: clean up legacy Markdown debt

* Replace legacy inline-code delimiters in README and example docs;
* Align the EXAMPLES.md table and remove FAQ's duplicate H1;
* Add the required EOF marker to the example documentation;
* Normalize completed TODO checklist entries and close the stale docs item;
* Record the Markdown cleanup in CHANGES.md;

* Improve xqsr3 RDoc reference quality

- Give generated RDoc an xqsr3-specific title and API-only navigation;
- Exclude Markdown, project boilerplate, gemspecs, and gem archives;
- Replace placeholder and legacy markup in public API descriptions;
- Document the completed reference work and align the Ruby helper standard;

* Package xqsr3 authored documentation

- Include the component catalogue, guides, and reference README in the gem;
- Keep generated RDoc output excluded from package contents;
- Record the documentation packaging change in the release notes;

* Finalize xqsr3 0.39.11 release notes

- Record component guides, RDoc improvements, CI coverage, and metadata
  updates.
- Document authored documentation packaging while excluding generated
  output;
- Correct release-note wording for cross-platform RDoc helper changes;

---------

Co-authored-by: Matt Wilson <152443343+mwsis@users.noreply.github.com>
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Reviewers

@synesissoftware synesissoftware Awaiting requested review from synesissoftware

Assignees

@mwsis mwsis

Labels

None yet

Projects

None yet

Milestone

No milestone

Development

Successfully merging this pull request may close these issues.

2 participants

@mwsis @synesissoftware