diff --git a/.github/workflows/ruby.yml b/.github/workflows/ruby.yml index a641a80..7ef66b7 100644 --- a/.github/workflows/ruby.yml +++ b/.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: diff --git a/docs/reference/README.md b/docs/reference/README.md new file mode 100644 index 0000000..0abe7ac --- /dev/null +++ b/docs/reference/README.md @@ -0,0 +1,37 @@ +# xqsr3 Generated API Reference + +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. + + + diff --git a/generate_rdoc.sh b/generate_rdoc.sh index e7dc865..2293738 100755 --- a/generate_rdoc.sh +++ b/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/ \ diff --git a/lib/xqsr3/conversion/bool_parser.rb b/lib/xqsr3/conversion/bool_parser.rb index e71d0a2..9505b0c 100644 --- a/lib/xqsr3/conversion/bool_parser.rb +++ b/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 diff --git a/lib/xqsr3/doc_.rb b/lib/xqsr3/doc_.rb index b3f8685..6a1b677 100644 --- a/lib/xqsr3/doc_.rb +++ b/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 diff --git a/lib/xqsr3/extensions/hash/slice.rb b/lib/xqsr3/extensions/hash/slice.rb index df34b35..e08c429 100644 --- a/lib/xqsr3/extensions/hash/slice.rb +++ b/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 = {} diff --git a/lib/xqsr3/extensions/integer/to_s_grp.rb b/lib/xqsr3/extensions/integer/to_s_grp.rb index f99a243..fcbcb97 100644 --- a/lib/xqsr3/extensions/integer/to_s_grp.rb +++ b/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 diff --git a/lib/xqsr3/extensions/string/map_option_string.rb b/lib/xqsr3/extensions/string/map_option_string.rb index e0dbd95..d04fd45 100644 --- a/lib/xqsr3/extensions/string/map_option_string.rb +++ b/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