decode 0.25.0 → 0.26.0

data/lib/decode/comment/example.rb

@@ -0,0 +1,62 @@
+# frozen_string_literal: true
+
+# Released under the MIT License.
+# Copyright, 2025, by Samuel Williams.
+
+require_relative "tag"
+
+module Decode
+	module Comment
+		# Represents a code example with an optional title.
+		#
+		# - `@example Title`
+		# - `@example`
+		#
+		# Should contain nested text lines representing the example code.
+		class Example < Tag
+			# Parse an example directive from text.
+			# @parameter directive [String] The directive name.
+			# @parameter text [String?] The optional title text.
+			# @parameter lines [Array(String)] The remaining lines.
+			# @parameter tags [Tags] The tags parser.
+			# @parameter level [Integer] The indentation level.
+			def self.parse(directive, text, lines, tags, level = 0)
+				node = self.new(directive, text)
+				
+				tags.parse(lines, level + 1) do |child|
+					node.add(child)
+				end
+				
+				return node
+			end
+			
+			# Initialize a new example tag.
+			# @parameter directive [String] The directive name.
+			# @parameter title [String?] The optional title for the example.
+			def initialize(directive, title = nil)
+				super(directive)
+				
+				# @type ivar @title: String?
+				@title = title&.strip unless title&.empty?
+			end
+			
+			# @attribute [String?] The title of the example.
+			attr :title
+			
+			# Get the example code as a single string with leading indentation removed.
+			# @returns [String?] The example code joined with newlines, or nil if no code.
+			def code
+				lines = text
+				return unless lines
+				
+				# Get the indentation from the first line
+				if indentation = lines.first[/\A\s+/]
+					# Remove the base indentation from all lines
+					lines = lines.map{|line| line.sub(indentation, "")}
+				end
+				
+				return lines.join("\n")
+			end
+		end
+	end
+end

data/lib/decode/comment/option.rb

@@ -1,7 +1,7 @@
 # frozen_string_literal: true
 
 # Released under the MIT License.
-# Copyright, 2024, by Samuel Williams.
+# Copyright, 2024-2025, by Samuel Williams.
 
 require_relative "parameter"
 

data/lib/decode/comment/tag.rb

@@ -21,6 +21,7 @@ module Decode
 			def self.build(directive, match)
 				raise NotImplementedError, "Subclasses must implement build method"
 			end
+			
 			# Build a pattern for bracketed content, supporting nested brackets.
 			# @parameter name [Symbol] The name of the group.
 			# @returns [String] The pattern.

data/lib/decode/documentation.rb

@@ -15,6 +15,7 @@ require_relative "comment/raises"
 require_relative "comment/returns"
 require_relative "comment/throws"
 require_relative "comment/yields"
+require_relative "comment/example"
 
 module Decode
 	# Structured access to a set of comment lines.

data/lib/decode/language/generic.rb

@@ -27,6 +27,8 @@ module Decode
 				
 				tags["public"] = Comment::Pragma
 				tags["private"] = Comment::Pragma
+				
+				tags["example"] = Comment::Example
 			end
 			
 			# Initialize a new generic language.

data/lib/decode/language/ruby/generic.rb

@@ -34,6 +34,8 @@ module Decode
 					tags["public"] = Comment::Pragma
 					tags["private"] = Comment::Pragma
 					
+					tags["example"] = Comment::Example
+					
 					tags["rbs"] = Comment::RBS
 				end
 				

data/lib/decode/language/ruby/parser.rb

@@ -404,8 +404,8 @@ module Decode
 					saved_visibility = @visibility
 					@visibility = visibility
 					yield
-						ensure
-							@visibility = saved_visibility
+				ensure
+					@visibility = saved_visibility
 				end
 				
 				NAME_ATTRIBUTE = /\A@name\s+(?<value>.*?)\Z/

data/lib/decode/rbs/type.rb

@@ -1,7 +1,7 @@
 # frozen_string_literal: true
 
 # Released under the MIT License.
-# Copyright, 2024, by Samuel Williams.
+# Copyright, 2025, by Samuel Williams.
 
 require "rbs"
 require "console"
@@ -49,4 +49,4 @@ module Decode
 			end
 		end
 	end
-end 
+end 

data/lib/decode/scope.rb

@@ -1,7 +1,7 @@
 # frozen_string_literal: true
 
 # Released under the MIT License.
-# Copyright, 2020-2024, by Samuel Williams.
+# Copyright, 2020-2025, by Samuel Williams.
 
 require_relative "definition"
 

data/lib/decode/version.rb

@@ -5,5 +5,5 @@
 
 module Decode
 	# @constant [String] The version of the gem.
-	VERSION = "0.25.0"
+	VERSION = "0.26.0"
 end

data/readme.md

@@ -14,14 +14,20 @@ Please see the [project documentation](https://socketry.github.io/decode/) for m
 
   - [Getting Started](https://socketry.github.io/decode/guides/getting-started/index) - This guide explains how to use `decode` for source code analysis.
 
-  - [Code Coverage](https://socketry.github.io/decode/guides/code-coverage/index) - This guide explains how to compute documentation code coverage.
+  - [Documentation Coverage](https://socketry.github.io/decode/guides/documentation-coverage/index) - This guide explains how to test and monitor documentation coverage in your Ruby projects using the Decode gem's built-in bake tasks.
 
   - [Extract Symbols](https://socketry.github.io/decode/guides/extract-symbols/index) - This example demonstrates how to extract symbols using the index. An instance of <code class="language-ruby">Decode::Index</code> is used for loading symbols from source code files. These symbols are available as a flat list and as a trie structure. You can look up specific symbols using a reference using <code class="language-ruby">Decode::Index\#lookup</code>.
 
+  - [Ruby Documentation](https://socketry.github.io/decode/guides/ruby-documentation/index) - This guide covers documentation practices and pragmas supported by the Decode gem for documenting Ruby code. These pragmas provide structured documentation that can be parsed and used to generate API documentation and achieve complete documentation coverage.
+
 ## Releases
 
 Please see the [project releases](https://socketry.github.io/decode/releases/index) for all releases.
 
+### v0.26.0
+
+  - Add support for `@example` pragmas in Ruby documentation comments.
+
 ### v0.25.0
 
   - Singleton classes are not relevant for coverage, so they are now ignored by the coverage reporter.

data/releases.md

@@ -1,5 +1,9 @@
 # Releases
 
+## v0.26.0
+
+  - Add support for `@example` pragmas in Ruby documentation comments.
+
 ## v0.25.0
 
   - Singleton classes are not relevant for coverage, so they are now ignored by the coverage reporter.

data.tar.gz.sig

@@ -1,3 +1 @@
-eE�,V�7U��.��~�Zc�g$Ȝ���C�,M�#7\d0_gag�e_]� 8+E6!9�./��b]��q�D%r��
-�R#=`|��9��R�ݍ�_���,M��
-��3I �n�j��C�PƎ`�IC�e������#�R-e�[y +�T���c���lt�(.��D_�5J�KO�%c=�~
+s�]f����w��b�C˦�MOJ��ƛ瞾ן��\#hnR}�?|6�\�i��`��sN����k3���b�d�)�2*2�~��6iw�!E���a�~��ՠ��SG¨b��3@��Sx|��Q���4���h��P�e1���w3By�[���e_М�U5��ŠK�aHVX�jc��ҝ�+v������k���O�����
y��^2��{X�#��.m�"��7���4?[�c��=��3�������
�|Q�ln
��Ў��x��Hl�6�e���H�륹H���D�����'����_A���䈡Ԡ�$���m![p%`aF\��E3�P�������Q�(NO:������h���4}�g���H��ZMy$�4

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: decode
 version: !ruby/object:Gem::Version
-  version: 0.25.0
+  version: 0.26.0
 platform: ruby
 authors:
 - Samuel Williams
@@ -73,13 +73,14 @@ files:
 - agent.md
 - bake/decode/index.rb
 - bake/decode/rbs.rb
-- context/coverage.md
+- context/documentation-coverage.md
 - context/getting-started.md
+- context/index.yaml
 - context/ruby-documentation.md
-- context/types.md
 - lib/decode.rb
 - lib/decode/comment/attribute.rb
 - lib/decode/comment/constant.rb
+- lib/decode/comment/example.rb
 - lib/decode/comment/node.rb
 - lib/decode/comment/option.rb
 - lib/decode/comment/parameter.rb
@@ -156,7 +157,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 3.6.9
+rubygems_version: 3.7.2
 specification_version: 4
 summary: Code analysis for documentation generation.
 test_files: []

data/context/coverage.md

@@ -1,325 +0,0 @@
-# Documentation Coverage
-
-This guide explains how to test and monitor documentation coverage in your Ruby projects using the Decode gem's built-in bake tasks.
-
-## Available Bake Tasks
-
-The Decode gem provides several bake tasks for analyzing your codebase:
-
-- `bake decode:index:coverage` - Check documentation coverage.
-- `bake decode:index:symbols` - List all symbols in the codebase.
-- `bake decode:index:documentation` - Extract all documentation.
-
-## Checking Documentation Coverage
-
-### Basic Coverage Check
-
-```bash
-# Check coverage for the lib directory:
-bake decode:index:coverage lib
-
-# Check coverage for a specific directory:
-bake decode:index:coverage app/models
-```
-
-### Understanding Coverage Output
-
-When you run the coverage command, you'll see output like:
-
-```
-15 definitions have documentation, out of 20 public definitions.
-
-Missing documentation for:
-- MyGem::SomeClass#method_name
-- MyGem::AnotherClass
-- MyGem::Utility.helper_method
-```
-
-The coverage check:
-- **Counts only public definitions** (public methods, classes, modules).
-- **Reports the ratio** of documented vs total public definitions.
-- **Lists missing documentation** by qualified name.
-- **Fails with an error** if coverage is incomplete.
-
-### What Counts as "Documented"
-
-A definition is considered documented if it has:
-- Any comment preceding it.
-- Documentation pragmas (like `@parameter`, `@returns`).
-- A `@namespace` pragma (for organizational modules).
-
-```ruby
-# Represents a user in the system.
-class MyClass
-end
-
-# @namespace
-module OrganizationalModule
-  # Contains helper functionality.
-end
-
-# Process user data and return formatted results.
-# @parameter name [String] The user's name.
-# @returns [bool] Success status.
-def process(name)
-  # Validation logic here:
-  return false if name.empty?
-  
-  # Processing logic:
-  true
-end
-
-class UndocumentedClass
-end
-```
-
-## Analyzing Symbols
-
-### List All Symbols
-
-```bash
-# See the structure of your codebase
-bake decode:index:symbols lib
-```
-
-This shows the hierarchical structure of your code:
-
-```
-[] -> []
-["MyGem"] -> [#<Decode::Language::Ruby::Module:...>]
-  MyGem
-["MyGem", "User"] -> [#<Decode::Language::Ruby::Class:...>]
-    MyGem::User
-["MyGem", "User", "initialize"] -> [#<Decode::Language::Ruby::Method:...>]
-      MyGem::User#initialize
-```
-
-### Extract Documentation
-
-```bash
-# Extract all documentation from your codebase
-bake decode:index:documentation lib
-```
-
-This outputs formatted documentation for all documented definitions:
-
-~~~markdown
-## `MyGem::User#initialize`
-
-Initialize a new user with the given email address.
-
-## `MyGem::User#authenticate`
-
-Authenticate the user with a password.
-Returns true if authentication is successful.
-~~~
-
-## Achieving 100% Coverage
-
-### Strategy for Complete Coverage
-
-1. **Document all public APIs**
-   ```ruby
-   # Represents a user management system.
-   class User
-     # @attribute [String] The user's email address.
-     attr_reader :email
-     
-     # Initialize a new user.
-     # @parameter email [String] The user's email address.
-     def initialize(email)
-       # Store the email address:
-       @email = email
-     end
-   end
-   ```
-
-2. **Use @namespace for organizational modules**
-   ```ruby
-   # @namespace
-   module MyGem
-     # Contains the main functionality.
-   end
-   ```
-
-3. **Document edge cases**
-   ```ruby
-   # @private
-   def internal_helper
-     # Internal implementation details.
-   end
-   ```
-
-### Common Coverage Issues
-
-**Issue: Missing namespace documentation**
-```ruby
-# This module has no documentation and will show as missing coverage:
-module MyGem
-end
-
-# Solution: Add @namespace pragma:
-# @namespace
-module MyGem
-  # Provides core functionality.
-end
-```
-
-**Issue: Undocumented methods**
-
-Problem: Methods without any comments will show as missing coverage:
-```ruby
-def process_data
-  # Implementation here
-end
-```
-
-Solution: Add description and pragmas:
-```ruby
-# Process the input data and return results.
-# @parameter data [Hash] Input data to process.
-# @returns [Array] Processed results.
-def process_data(data)
-  # Process the input:
-  results = data.map { |item| transform(item) }
-  
-  # Return processed results:
-  results
-end
-```
-
-**Issue: Missing attr documentation**
-
-Problem: Attributes without documentation will show as missing coverage:
-```ruby
-attr_reader :name
-```
-
-Solution: Document with @attribute pragma:
-```ruby
-# @attribute [String] The user's full name.
-attr_reader :name
-```
-
-## Integrating into CI/CD
-
-### GitHub Actions Example
-
-```yaml
-name: Documentation Coverage
-
-on: [push, pull_request]
-
-jobs:
-  docs:
-    runs-on: ubuntu-latest
-    steps:
-      - uses: actions/checkout@v3
-      - uses: ruby/setup-ruby@v1
-        with:
-          bundler-cache: true
-      - name: Check documentation coverage
-        run: bake decode:index:coverage lib
-```
-
-### Rake Task Integration
-
-Add to your `Rakefile`:
-
-```ruby
-require 'decode'
-
-desc "Check documentation coverage"
-task :doc_coverage do
-  system("bake decode:index:coverage lib") || exit(1)
-end
-
-task default: [:test, :doc_coverage]
-```
-
-## Monitoring Coverage Over Time
-
-### Generate Coverage Reports
-
-```ruby
-# Generate a coverage percentage for the specified directory.
-# @parameter root [String] The root directory to analyze.
-# @returns [Float] The coverage percentage.
-def coverage_percentage(root)
-  index = Decode::Index.new
-  index.update(Dir.glob(File.join(root, "**/*.rb")))
-  
-  documented = 0
-  total = 0
-  
-  index.trie.traverse do |path, node, descend|
-    node.values&.each do |definition|
-      if definition.coverage_relevant?
-        total += 1
-        documented += 1 if definition.comments&.any?
-      end
-    end
-    descend.call if node.values.nil?
-  end
-  
-  (documented.to_f / total * 100).round(2)
-end
-
-puts "Coverage: #{coverage_percentage('lib')}%"
-```
-
-### Exclude Patterns
-
-If you need to exclude certain files from coverage:
-
-```ruby
-# Custom coverage script with exclusions.
-paths = Dir.glob("lib/**/*.rb").reject do |path|
-  # Exclude vendor files and test files:
-  path.include?('vendor/') || path.end_with?('_test.rb')
-end
-
-index = Decode::Index.new
-index.update(paths)
-# ... continue with coverage analysis
-```
-
-## Best Practices
-
-1. **Run coverage checks regularly** - Include in your CI pipeline
-2. **Set coverage targets** - Aim for 100% coverage of public APIs
-3. **Document incrementally** - Add documentation as you write code
-4. **Use meaningful descriptions** - Don't just add empty comments
-5. **Leverage @namespace** - For modules that only serve as containers
-6. **Review coverage reports** - Use the missing documentation list to prioritize
-
-## Troubleshooting
-
-### Common Error Messages
-
-**"Insufficient documentation!"**
-- Some public definitions are missing documentation
-- Check the list of missing items and add appropriate comments
-
-**No output from coverage command**
-- Verify the path exists: `bake decode:index:coverage lib`
-- Check that Ruby files exist in the specified directory
-
-**Coverage shows 0/0 definitions**
-- The directory might not contain any Ruby files
-- Try a different path or check your file extensions
-
-### Debug Coverage Issues
-
-```bash
-# First, see what symbols are being detected
-bake decode:index:symbols lib
-
-# Then check what documentation exists
-bake decode:index:documentation lib
-
-# Finally, run coverage to see what's missing
-bake decode:index:coverage lib
-```
-
-This workflow helps you understand what the tool is detecting and why certain items might be missing documentation.

data/context/types.md

@@ -1,127 +0,0 @@
-# Setting Up RBS Types and Steep Type Checking for Ruby Gems
-
-This guide covers the process for establishing robust type checking in Ruby gems using RBS and Steep, focusing on automated generation from source documentation and proper validation.
-
-## Core Process
-
-### Documentation-Driven RBS Generation
-
-Generate RBS files from documentation:
-
-```bash
-bake decode:rbs:generate lib > sig/example/gem.rbs`
-```
-
-At a minimum, add `@parameter`, `@attribute` and `@returns` documentation to all public methods.
-
-#### Parametric Types
-
-Use `@rbs generic` comments to define type parameters for classes and modules:
-
-```ruby
-# @rbs generic T
-class Container
-	# @parameter item [T] The item to store
-	def initialize(item)
-		@item = item
-	end
-	
-	# @returns [T] The stored item
-	def get
-		@item
-	end
-end
-```
-
-Use `@rbs` comments for parametric method signatures:
-
-```ruby
-# From above:
-class Container
-	# @rbs () { (T) -> void } -> void
-	def each
-		yield @item
-	end
-```
-
-#### Interfaces
-
-Create interfaces in `sig/example/gem/interface.rbs`:
-
-```rbs
-module Example
-	module Gem
-		interface _Interface
-		end
-	end
-end
-```
-
-You can use the interface in `@parameter`, `@attribute` and `@returns` types.
-
-### Testing
-
-Run tests using the `steep` gem.
-
-```bash
-steep check
-```
-
-**Process**: Start with basic generation, then refine based on Steep feedback.
-
-1. Generate initial RBS from documentation
-2. Run `steep check lib` to identify issues
-3. Fix structural problems (inheritance, missing docs)
-4. Iterate until clean validation
-
-### Deploymnet
-
-Make sure `bake-test-types` is added to the `test` group in `gems.rb` (or `Gemfile`).
-
-```ruby
-group :test do
-	# ...
-	gem "bake-test"
-	gem "bake-test-external"
-	gem "bake-test-types"
-	# ...
-end
-```
-
-Then, create `.github/workflows/test-types.yaml`:
-
-```yaml
-name: Test Types
-
-on: [push, pull_request]
-
-permissions:
-  contents: read
-
-env:
-  CONSOLE_OUTPUT: XTerm
-
-jobs:
-  test:
-    name: ${{matrix.ruby}} on ${{matrix.os}}
-    runs-on: ${{matrix.os}}-latest
-    
-    strategy:
-      matrix:
-        os:
-          - ubuntu
-        
-        ruby:
-          - "3.4"
-    
-    steps:
-    - uses: actions/checkout@v4
-    - uses: ruby/setup-ruby@v1
-      with:
-        ruby-version: ${{matrix.ruby}}
-        bundler-cache: true
-    
-    - name: Run tests
-      timeout-minutes: 10
-      run: bundle exec bake test:types
-```