decode 0.25.0 → 0.27.0

data/context/getting-started.md

@@ -1,242 +1,54 @@
-# Getting Started with Decode
+# Getting Started
 
-The Decode gem provides programmatic access to Ruby code structure and metadata. It can parse Ruby files and extract definitions, comments, and documentation pragmas, enabling code analysis, documentation generation, and other programmatic manipulations of Ruby codebases.
+This guide explains how to use `decode` for source code analysis.
 
 ## Installation
 
-Add to your Gemfile:
+Add the gem to your project:
 
-```ruby
-gem 'decode'
-```
+~~~ bash
+$ bundle add decode
+~~~
 
-Or install directly:
+## Indexing
 
-```bash
-bundle add decode
-```
+`decode` turns your source code into a kind of database with rich access to definitions, segments and associated comments. Use {ruby Decode::Index} to build an index of your project by loading in source files:
 
-## Basic Usage
+~~~ ruby
+require 'decode/index'
 
-### Analyzing a Ruby File
-
-```ruby
-require 'decode'
-
-# Create a source object:
-source = Decode::Source.new('lib/my_class.rb', Decode::Language::Ruby.new)
-
-# Extract definitions (classes, methods, etc.):
-definitions = source.definitions.to_a
-
-definitions.each do |definition|
-  puts "#{definition.name}: #{definition.short_form}"
-end
-```
+index = Decode::Index.new
 
-### Extracting Documentation
+# Load all Ruby files into the index:
+index.update(Dir['**/*.rb'])
+~~~
 
-```ruby
-# Get segments (blocks of comments + code):
-segments = source.segments.to_a
+Once you've done this, you can print out all the definitions from your project:
 
-segments.each do |segment|
-  puts "Comments: #{segment.comments.join(' ')}"
-  puts "Code: #{segment.code}"
+~~~ ruby
+index.definitions.each do |name, symbol|
+	puts symbol.long_form
 end
-```
-
-### Checking Documentation Coverage
+~~~
 
-```ruby
-# Check which definitions have documentation:
-definitions.each do |definition|
-  status = definition.comments.any? ? 'documented' : 'missing docs'
-  puts "#{definition.name}: #{status}"
-end
-```
-
-## Working with Documentation Pragmas
-
-The Decode gem understands structured documentation pragmas:
-
-```ruby
-# This will be parsed and structured:
-source_code = <<~RUBY
-  # Represents a user in the 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.
-    # @parameter options [Hash] Additional options.
-    # @option :active [bool] Whether the account is active.
-    # @raises [ArgumentError] If email is invalid.
-    def initialize(email, options = {})
-      # Validate the email format:
-      raise ArgumentError, "Invalid email" if email.empty?
-      
-      # Set instance variables:
-      @email = email
-      @active = options.fetch(:active, true)
-    end
-  end
-RUBY
-
-# Parse and analyze:
-result = Decode::Language::Ruby.new.parser.parse_source(source_code)
-definitions = Decode::Language::Ruby.new.parser.definitions_for(source_code).to_a
-
-definitions.each do |definition|
-  puts "#{definition.name}: #{definition.comments.join(' ')}"
-end
-```
-
-## Common Use Cases
-
-### 1. Code Analysis and Metrics
-
-```ruby
-# Analyze a codebase and return metrics.
-# @parameter file_path [String] Path to the Ruby file to analyze.
-def analyze_codebase(file_path)
-  source = Decode::Source.new(file_path, Decode::Language::Ruby.new)
-  definitions = source.definitions.to_a
-  
-  # Count different definition types:
-  classes = definitions.count { |d| d.is_a?(Decode::Language::Ruby::Class) }
-  methods = definitions.count { |d| d.is_a?(Decode::Language::Ruby::Method) }
-  modules = definitions.count { |d| d.is_a?(Decode::Language::Ruby::Module) }
-  
-  puts "Classes: #{classes}, Methods: #{methods}, Modules: #{modules}"
-end
-```
-
-### 2. Documentation Coverage Reports
-
-```ruby
-# Calculate documentation coverage for a file.
-# @parameter file_path [String] Path to the Ruby file to analyze.
-def documentation_coverage(file_path)
-  source = Decode::Source.new(file_path, Decode::Language::Ruby.new)
-  definitions = source.definitions.to_a
-  
-  # Calculate coverage statistics:
-  total = definitions.count
-  documented = definitions.count { |d| d.comments.any? }
-  
-  puts "Coverage: #{documented}/#{total} (#{(documented.to_f / total * 100).round(1)}%)"
-end
-```
-
-### 3. Extracting API Information
-
-```ruby
-# Extract API information from a Ruby file.
-# @parameter file_path [String] Path to the Ruby file to analyze.
-def extract_api_info(file_path)
-  source = Decode::Source.new(file_path, Decode::Language::Ruby.new)
-  definitions = source.definitions.to_a
-  
-  # Get public methods only:
-  public_methods = definitions.select do |definition|
-    definition.is_a?(Decode::Language::Ruby::Method) && 
-    definition.visibility == :public
-  end
-  
-  public_methods.each do |method|
-    puts "#{method.long_form}"
-    puts "  Comments: #{method.comments.join(' ')}" if method.comments.any?
-  end
-end
-```
-
-### 4. Code Structure Analysis
-
-```ruby
-# Analyze the structure of Ruby files in a directory.
-# @parameter directory [String] Path to the directory to analyze.
-def analyze_structure(directory)
-  Dir.glob("#{directory}/**/*.rb").each do |file|
-    source = Decode::Source.new(file, Decode::Language::Ruby.new)
-    definitions = source.definitions.to_a
-    
-    # Find nested classes and modules:
-    nested = definitions.select { |d| d.parent }
-    
-    if nested.any?
-      puts "#{file}:"
-      nested.each do |definition|
-        puts "  #{definition.qualified_name}"
-      end
-    end
-  end
-end
-```
-
-### 5. Finding Undocumented Code
-
-```ruby
-# Find undocumented code in a directory.
-# @parameter directory [String] Path to the directory to analyze.
-def find_undocumented(directory)
-  Dir.glob("#{directory}/**/*.rb").each do |file|
-    source = Decode::Source.new(file, Decode::Language::Ruby.new)
-    definitions = source.definitions.to_a
-    
-    # Filter for undocumented public definitions:
-    undocumented = definitions.select { |d| d.comments.empty? && d.visibility == :public }
-    
-    if undocumented.any?
-      puts "#{file}:"
-      undocumented.each do |definition|
-        puts "  - #{definition.short_form}"
-      end
-    end
-  end
-end
-```
-
-## Advanced Features
-
-### Using the Index
-
-```ruby
-# Create an index for multiple files:
-index = Decode::Index.new
-index.update(Dir.glob("lib/**/*.rb"))
-
-# Search through the index:
-index.trie.traverse do |path, node, descend|
-  if node.values
-    node.values.each do |definition|
-      puts "#{path.join('::')} - #{definition.short_form}"
-    end
-  end
-  descend.call
-end
-```
+## References
 
-### Custom Language Support
+References are strings which can be resolved into definitions. The index allows you to efficiently resolve references.
 
-```ruby
-# The decode gem is extensible:
-language = Decode::Language::Generic.new("custom")
-# You can implement your own parser for other languages:
-```
+~~~ ruby
+# Lookup a specific symbol:
+reference = index.languages.parse_reference("ruby Decode::Index#lookup")
+definition = index.lookup(reference).first
+puts definition.long_form
+~~~
 
-## Tips for Effective Usage
+## Documentation
 
-1. **Use structured pragmas** - They help tools understand your code better.
-2. **Leverage programmatic access** - Build tools that analyze and manipulate code.
-3. **Use @namespace** - For organizational modules to achieve complete coverage.
-4. **Analyze code patterns** - Use decode to understand codebase structure.
-5. **Build automation** - Use decode in CI/CD pipelines for code quality checks.
+The {ruby Decode::Documentation} provides rich access to the comments that preceed a definition. This includes metadata including `@parameter`, `@returns` and other tags.
 
-## Next Steps
+~~~ ruby
+lines = definition.documentation.text
+puts lines
+~~~
 
-- See [Ruby Documentation](ruby-documentation.md) for complete pragma reference.
-- Check out [Documentation Coverage](coverage.md) for coverage monitoring.
-- Use decode to build code analysis tools for your projects.
-- Integrate decode into your development workflow and CI/CD pipelines.
+See {ruby Decode::Comment::Node#traverse} for more details about how to consume this data.

data/context/index.yaml

@@ -0,0 +1,22 @@
+# Automatically generated context index for Utopia::Project guides.
+# Do not edit then files in this directory directly, instead edit the guides and then run `bake utopia:project:agent:context:update`.
+---
+description: Code analysis for documentation generation.
+metadata:
+  documentation_uri: https://socketry.github.io/decode/
+  funding_uri: https://github.com/sponsors/socketry/
+  source_code_uri: https://github.com/socketry/decode.git
+files:
+- path: getting-started.md
+  title: Getting Started
+  description: This guide explains how to use `decode` for source code analysis.
+- path: documentation-coverage.md
+  title: Documentation Coverage
+  description: This guide explains how to test and monitor documentation coverage
+    in your Ruby projects using the Decode gem's built-in bake tasks.
+- path: ruby-documentation.md
+  title: Ruby Documentation
+  description: 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.

data/context/ruby-documentation.md

@@ -8,32 +8,38 @@ This guide covers documentation practices and pragmas supported by the Decode ge
 
 #### Definition Documentation
 
-- **Full sentences**: All documentation for definitions (classes, modules, methods) should be written as complete sentences with proper grammar and punctuation.
-- **Class documentation**: Documentation for classes should generally start with "Represents a ..." to clearly indicate what the class models or encapsulates.
-- **Method documentation**: Should clearly describe what the method does, not how it does it.
-- **Markdown format**: All documentation comments are written in Markdown format, allowing for rich formatting including lists, emphasis, code blocks, and links.
+- Full sentences: All documentation for definitions (classes, modules, methods) should be written as complete sentences with proper grammar and punctuation.
+- Class documentation: Should directly describe what the class *is* or *does*.
+	- For data/model classes, "A user account in the system." works well.
+	- For functional classes (servers, clients, connections), lead with what the class does: "An HTTP client that manages persistent connections...".
+- Method documentation: Should clearly describe what the method does, not how it does it.
+- Markdown format: All documentation comments are written in Markdown format, allowing for rich formatting including lists, emphasis, code blocks, and links.
 
 #### Inline Code Comments
 
-- **Explanatory comments**: Comments within methods that explain specific lines or sections of code should end with a colon `:` to distinguish them from definition documentation.
-- **Purpose**: These comments explain the reasoning behind specific implementation details.
+- Explanatory comments: Comments within methods that explain specific lines or sections of code should end with a colon `:` to distinguish them from definition documentation.
+- Purpose: These comments explain the reasoning behind specific implementation details.
 
 #### Links and Code Formatting
 
-- **Curly braces `{}`**: Use curly braces to create links to other methods, classes, or modules. The Decode gem uses `@index.lookup(text)` to resolve these references.
-	- **Absolute references**: `{Decode::Index#lookup}` - Links to a specific method in a specific class
-	- **Relative references**: `{lookup}` - Links to a method in the current scope or class
-	- **Class references**: `{User}` - Links to a class or module
-- **Backticks**: Use backticks for code formatting of symbols, values, method names, and technical terms that should appear in monospace font.
-	- **Symbols**: `:admin`, `:user`, `:guest`
-	- **Values**: `true`, `false`, `nil`
-	- **Technical terms**: `attr_*`, `catch`/`throw`
-	- **Code expressions**: `**options`
+- Curly braces `{}`: Use curly braces to create links to other methods, classes, or modules. The Decode gem uses `@index.lookup(text)` to resolve these references.
+  - Absolute references: `{Decode::Index#lookup}` - Links to a specific method in a specific class
+  - Relative references: `{lookup}` - Links to a method in the current scope or class
+  - Class references: `{User}` - Links to a class or module
+- Backticks: Use backticks for code formatting of symbols, values, method names, and technical terms that should appear in monospace font.
+  - Symbols: `:admin`, `:user`, `:guest`
+  - Values: `true`, `false`, `nil`
+  - Technical terms: `attr_*`, `catch`/`throw`
+  - Code expressions: `**options`
 
 #### Examples
 
+##### Data/Model Classes
+
+For classes that model domain concepts, describe what the class is:
+
 ```ruby
-# Represents a user account in the system.
+# A user account in the system.
 class User
 	# @attribute [String] The user's email address.
 	attr_reader :email
@@ -70,26 +76,35 @@ class User
 		true
 	end
 end
+```
 
-# Represents a collection of users with search capabilities.
-class UserCollection
-	# Find users matching the given criteria.
-	# @parameter criteria [Hash] Search parameters.
-	# @returns [Array(User)] Matching users.
-	def find(**criteria)
-		# Start with all users:
-		results = @users.dup
-		
-		# Apply each filter criterion:
-		criteria.each do |key, value|
-			results = filter_by(results, key, value)
-		end
-		
-		results
+##### Functional/Service Classes
+
+For classes that *do* something (clients, servers, processors), lead with what the class does:
+
+```ruby
+# An HTTP client that manages persistent connections to a remote server, with automatic retries for idempotent requests.
+class Client
+	# Send a request to the remote server.
+	# @parameter request [Protocol::HTTP::Request] The request to send.
+	# @returns [Protocol::HTTP::Response] The response from the server.
+	def call(request)
+		# ...
+	end
+	
+	# Close the client and release all connections.
+	def close
+		# ...
 	end
 end
+
+# Raised when a connection to the remote server cannot be established.
+class ConnectionError < StandardError
+end
 ```
 
+Note the difference: `User` is described as a thing ("A user account..."), while `Client` is described by what it does ("An HTTP client that manages..."), and `ConnectionError` is described by when it occurs ("Raised when...").
+
 **Key formatting examples from above:**
 - `{disable!}` - Creates a link to the `disable!` method (relative reference)
 - `active?` - Formats the method name in monospace (backticks for code formatting)
@@ -98,14 +113,14 @@ end
 
 ### Best Practices
 
-1. **Be Consistent**: Use the same format for similar types of documentation.
-2. **Include Types**: Always specify types for parameters, returns, and attributes.
-3. **Be Descriptive**: Provide clear, actionable descriptions.
-4. **Document Exceptions**: Always document what exceptions might be raised.
-5. **Use Examples**: Include usage examples when the behavior isn't obvious.
-6. **Keep Updated**: Update documentation when you change the code.
-7. **Use @namespace wisely**: Apply to organizational modules to achieve 100% coverage.
-8. **Avoid redundancy**: For simple attributes and methods, attach descriptions directly to pragmas rather than repeating obvious information.
+1. Be Consistent: Use the same format for similar types of documentation.
+2. Include Types: Always specify types for parameters, returns, and attributes.
+3. Be Descriptive: Provide clear, actionable descriptions.
+4. Document Exceptions: Always document what exceptions might be raised.
+5. Use Examples: Include usage examples when the behavior isn't obvious.
+6. Keep Updated: Update documentation when you change the code.
+7. Use @namespace wisely: Apply to organizational modules to achieve 100% coverage.
+8. Avoid redundancy: For simple attributes and methods, attach descriptions directly to pragmas rather than repeating obvious information.
 
 #### Simple Attributes and Methods
 
@@ -155,7 +170,7 @@ Type signatures are used to specify the expected types of parameters, return val
 Documents class attributes, instance variables, and `attr_*` declarations. Prefer to have one attribute per line for clarity.
 
 ```ruby
-# Represents a person with basic attributes.
+# A person with basic attributes.
 class Person
 	# @attribute [String] The person's full name.
 	attr_reader :name
@@ -247,14 +262,14 @@ Documents block parameters and behavior.
 
 ```ruby
 # @yields {|item| ...} Each item in the collection.
-#   @parameter item [Object] The current item being processed.
+# 	@parameter item [Object] The current item being processed.
 def each_item(&block)
 	items.each(&block)
 end
 
 # @yields {|user, index| ...} User and their index.
-#   @parameter user [User] The current user.
-#   @parameter index [Integer] The user's position in the list.
+# 	@parameter user [User] The current user.
+# 	@parameter index [Integer] The user's position in the list.
 def each_user_with_index(&block)
 	users.each_with_index(&block)
 end
@@ -308,6 +323,39 @@ def fetch_data
 end
 ```
 
+### Example Code
+
+#### `@example Title?`
+
+Includes an example usage snippet for a method or definition. The `@example` directive can have an optional title on the same line, followed by one or more indented lines of code:
+
+```ruby
+# @example Create a new thing
+# 	thing = Thing.new
+# 	thing.process
+def process
+	# ...
+end
+```
+
+Behaviour:
+
+- The optional title is captured verbatim (e.g., `"Create a new thing"`).
+- Indented lines following the directive are captured as the example code.
+- When parsed, examples are available as `Decode::Comment::Example` nodes with:
+	- `title` – `String?`, the optional example title.
+	- `text` – `Array(String)?`, the raw code lines (including leading indentation).
+	- `code` – `String?`, the code as a single string with leading indentation removed (convenience).
+
+Multiple `@example` pragmas can be used on the same definition to show different scenarios.
+
+```ruby
+definition.documentation.filter(Decode::Comment::Example) do |example|
+	puts "Title: #{example.title.inspect}"
+	puts example.code # => joined string with indentation removed
+end
+```
+
 ### Namespace Documentation
 
 #### `@namespace`

data/lib/decode/comment/constant.rb

@@ -44,4 +44,4 @@ module Decode
 			attr :type
 		end
 	end
-end 
+end 

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/definition.rb

@@ -1,7 +1,7 @@
 # frozen_string_literal: true
 
 # Released under the MIT License.
-# Copyright, 2020-2025, by Samuel Williams.
+# Copyright, 2020-2026, by Samuel Williams.
 
 require_relative "location"
 
@@ -166,6 +166,14 @@ module Decode
 			false
 		end
 		
+		# Whether this definition represents an alias to another definition.
+		# Tools can use this to filter aliases from outputs without parsing text.
+		#
+		# @returns [bool] False by default; specific definition types may override.
+		def alias?
+			false
+		end
+		
 		# Whether this represents a single entity to be documented (along with it's contents).
 		#
 		# @returns [bool]

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/alias.rb

@@ -1,7 +1,7 @@
 # frozen_string_literal: true
 
 # Released under the MIT License.
-# Copyright, 2025, by Samuel Williams.
+# Copyright, 2025-2026, by Samuel Williams.
 
 require_relative "definition"
 
@@ -21,6 +21,18 @@ module Decode
 				
 				attr :old_name
 				
+				# Whether this definition represents an alias.
+				# @returns [bool] Always true for aliases.
+				def alias?
+					true
+				end
+				
+				# The original name this alias refers to.
+				# @returns [Symbol]
+				def aliased_name
+					@old_name
+				end
+				
 				# Aliases don't require separate documentation as they reference existing methods.
 				# @returns [bool] Always false for aliases.
 				def coverage_relevant?