### Install decode gem

Source: https://github.com/socketry/decode/blob/main/guides/getting-started/readme.md

Installs the decode gem into your Ruby project using the Bundler CLI.

```bash
bundle add decode
```

--------------------------------

### Index source files and list definitions

Source: https://github.com/socketry/decode/blob/main/guides/getting-started/readme.md

Initializes a new Decode index, loads Ruby source files into it, and iterates through the definitions to print their long-form representation.

```ruby
require 'decode/index'

index = Decode::Index.new

# Load all Ruby files into the index:
index.update(Dir['**/*.rb'])

index.definitions.each do |name, symbol|
	puts symbol.long_form
end
```

--------------------------------

### Parsing Documentation Examples

Source: https://github.com/socketry/decode/blob/main/guides/ruby-documentation/readme.md

Demonstrates how to filter and access documentation examples using the Decode gem's internal API. It shows how to retrieve titles and cleaned code blocks from comment nodes.

```ruby
definition.documentation.filter(Decode::Comment::Example) do |example|
	puts "Title: #{example.title.inspect}"
	puts example.code # => joined string with indentation removed
end
```

--------------------------------

### Ruby Code for Achieving 100% Coverage

Source: https://github.com/socketry/decode/blob/main/guides/documentation-coverage/readme.md

Provides Ruby code examples demonstrating how to achieve 100% documentation coverage. This includes documenting public APIs with comments and pragmas, using `@namespace` for organizational modules, documenting edge cases with `@private`, and documenting attributes using `@attribute`.

```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

# @namespace
module MyGem
	VERSION = "0.1.0"
end

# @private
def internal_helper
	# Add the fields:
	return foo + bar
end
```

--------------------------------

### Ruby Code Examples for Documentation Coverage

Source: https://github.com/socketry/decode/blob/main/guides/documentation-coverage/readme.md

Illustrates Ruby code constructs that are considered documented by the Decode gem, including classes with comments, modules with `@namespace` pragmas, and methods with parameter and return documentation. It also shows examples of undocumented code that would fail coverage checks.

```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
```

--------------------------------

### Solutions for Common Coverage Issues in Ruby

Source: https://github.com/socketry/decode/blob/main/guides/documentation-coverage/readme.md

Addresses common documentation coverage issues in Ruby projects, such as missing namespace documentation, undocumented methods, and missing attribute documentation. It provides code examples showing the problem and the corresponding solution using Decode's documentation pragmas.

```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

def process_data
	# Implementation here
end

# 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

attr_reader :name

# @attribute [String] The user's full name.
attr_reader :name
```

--------------------------------

### Resolve and lookup symbol references

Source: https://github.com/socketry/decode/blob/main/guides/getting-started/readme.md

Parses a reference string into a symbol and uses the index to look up the corresponding definition.

```ruby
# Lookup a specific symbol:
reference = index.languages.parse_reference("ruby Decode::Index#lookup")
definition = index.lookup(reference).first
puts definition.long_form
```

--------------------------------

### Install decode gem using Bundler

Source: https://github.com/socketry/decode/blob/main/context/getting-started.md

This snippet shows how to add the 'decode' gem to your project's Gemfile using the 'bundle add' command. It's a standard way to manage Ruby dependencies.

```bash
$ bundle add decode

```

--------------------------------

### Extract documentation from definitions

Source: https://github.com/socketry/decode/blob/main/guides/getting-started/readme.md

Accesses the documentation text associated with a definition, including metadata tags like @parameter and @returns.

```ruby
lines = definition.documentation.text
puts lines
```

--------------------------------

### Documenting Attributes and Parameters in Ruby

Source: https://github.com/socketry/decode/blob/main/context/ruby-documentation.md

Examples of using @attribute, @parameter, and @option tags to define class attributes and method arguments with their respective types.

```ruby
class Person
	# @attribute [String] The person's full name.
	attr_reader :name
	
	# @attribute [Integer] The person's age in years.
	attr_accessor :age
	
	# @attribute [Hash] Configuration settings.
	attr_writer :config
end

# @parameter x [Integer] The x coordinate.
# @parameter y [Integer] The y coordinate.
# @parameter options [Hash] Optional configuration.
def move(x, y, **options)
	# ...
end

# @parameter user [User] The user object.
# @option :cached [bool] Whether to cache the result.
# @option :timeout [Integer] Request timeout in seconds.
def fetch_user_data(user, **options)
	# ...
end
```

--------------------------------

### Check Documentation Coverage using Bake

Source: https://context7.com/socketry/decode/llms.txt

This snippet shows how to use the `bake` command-line tool to check documentation coverage for a Ruby project. It includes commands to check coverage for a directory, list all symbols, and extract all documentation. An example output demonstrates the format of coverage reports and potential errors.

```bash
# Check documentation coverage for a directory
$ bake decode:index:coverage lib

# Example output:
# 135 definitions have documentation, out of 215 public definitions.
#
# Missing documentation for:
# - Decode::Languages#freeze (lib/decode/languages.rb:33)
# - Decode::Trie::Node#lookup (lib/decode/trie.rb:41)
# RuntimeError: Insufficient documentation!

# List all symbols in the codebase
$ bake decode:index:symbols lib

# Extract all documentation
$ bake decode:index:documentation lib
```

--------------------------------

### Extract Documentation with Decode

Source: https://github.com/socketry/decode/blob/main/guides/documentation-coverage/readme.md

Extracts all documented definitions from a Ruby codebase using the Decode gem's `decode:index:documentation` bake task. The output is formatted in Markdown, providing documentation for each documented symbol.

```bash
# Extract all documentation from your codebase
bake decode:index:documentation lib
```

--------------------------------

### Ruby Class Documentation for User Collection Search

Source: https://github.com/socketry/decode/blob/main/context/ruby-documentation.md

Documents the 'UserCollection' class in Ruby, focusing on the 'find' method. It illustrates how to document parameters and return types using Decode pragmas and provides an example of inline code comments explaining the logic.

```ruby
# 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
	end
end
```

--------------------------------

### Check Documentation Coverage with Decode

Source: https://github.com/socketry/decode/blob/main/guides/documentation-coverage/readme.md

Executes a documentation coverage check for specified directories within a Ruby project using the Decode gem's bake task. It analyzes public definitions and reports the ratio of documented to total public definitions, listing any missing documentation. The task fails if coverage is incomplete.

```bash
# Check coverage for the lib directory:
bake decode:index:coverage lib

# Check coverage for a specific directory:
bake decode:index:coverage app/models
```

--------------------------------

### List Codebase Symbols with Decode

Source: https://github.com/socketry/decode/blob/main/guides/documentation-coverage/readme.md

Lists all symbols within a specified directory of a Ruby project using the Decode gem's `decode:index:symbols` bake task. This provides a hierarchical view of the codebase structure, showing modules, classes, and methods.

```bash
# See the structure of your codebase
bake decode:index:symbols lib
```

--------------------------------

### Working with Documentation Tags in Ruby

Source: https://context7.com/socketry/decode/llms.txt

This Ruby snippet demonstrates how to parse and traverse documentation tags within a definition's documentation using the `decode/index` library. It shows how to find a specific definition and then iterate through its documentation nodes, identifying and printing details for various tag types like @parameter, @returns, @raises, @example, and @pragma.

```ruby
require 'decode/index'

index = Decode::Index.for('lib')

# Find a method with rich documentation
ref = index.languages.parse_reference("ruby Decode::Index.for")
definition = index.lookup(ref)
doc = definition.documentation

# Iterate through all tag types
doc.traverse do |node, descend|
  case node
  when Decode::Comment::Parameter
    puts "@parameter #{node.name} [#{node.type}] #{node.text&.join(' ')}"
  when Decode::Comment::Returns
    puts "@returns [#{node.type}] #{node.text&.join(' ')}"
  when Decode::Comment::Raises
    puts "@raises [#{node.type}] #{node.text&.join(' ')}"
  when Decode::Comment::Yields
    puts "@yields #{node.text&.join(' ')}"
  when Decode::Comment::Example
    puts "@example #{node.title}"
    puts node.code
  when Decode::Comment::Pragma
    puts "@#{node.directive}"
  end

  descend.call(node) if node.respond_to?(:children) && node.children?
end

# Output:
# @parameter paths [Array(String)] Variable number of paths to index.
# @parameter languages [Languages] The languages to support in this index.
# @returns [Index] A new index populated with definitions from the given paths.
```

--------------------------------

### Add Rake Task for Decode Documentation Coverage (Ruby)

Source: https://github.com/socketry/decode/blob/main/context/documentation-coverage.md

This Ruby code adds a Rake task named 'doc_coverage' that executes the 'bake decode:index:coverage lib' command to check documentation coverage. It also configures the default Rake task to include 'doc_coverage'. Requires the 'decode' gem to be installed.

```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]
```

--------------------------------

### Generate RBS Type Signatures using Bake

Source: https://context7.com/socketry/decode/llms.txt

This snippet illustrates how to generate Ruby's RBS (Ruby Signature) type declarations using the `bake` command. It shows the command to generate signatures for a library and how to direct the output to standard output or a file. The example output displays the format of generated RBS declarations.

```bash
# Generate RBS signatures using bake
$ bake decode:rbs:generate lib

# Output RBS declarations to stdout:
# class Decode::Index
#   def self.for: (*String, ?languages: Languages) -> Index
#   def initialize: (?Languages) -> void
#   def lookup: (Language::Reference, ?relative_to: Definition?) -> Definition?
#   attr_reader languages: Languages
#   attr_reader definitions: Hash[String, Definition]
# end
# ...

# Save to a file
$ bake decode:rbs:generate lib > sig/decode.rbs
```

--------------------------------

### Documenting Method Returns and Exceptions

Source: https://github.com/socketry/decode/blob/main/guides/ruby-documentation/readme.md

Shows how to document the output of a method and the potential errors it might raise using @returns and @raises pragmas.

```ruby
# @returns [String] The formatted user name.
def full_name
	"#{first_name} #{last_name}"
end

# @parameter age [Integer] The person's age.
# @raises [ArgumentError] If age is negative.
# @raises [TypeError] If age is not an integer.
def set_age(age)
	raise ArgumentError, "Age cannot be negative" if age < 0
	raise TypeError, "Age must be an integer" unless age.is_a?(Integer)
	@age = age
end
```

--------------------------------

### Concise Attribute Documentation

Source: https://github.com/socketry/decode/blob/main/guides/ruby-documentation/readme.md

Shows the recommended practice for documenting simple attributes by attaching descriptions directly to the pragma to avoid redundancy.

```ruby
# Good - concise and clear:
# @attribute [String] The name of the parameter.
attr :name
```

--------------------------------

### Build a source code index with Decode::Index

Source: https://github.com/socketry/decode/blob/main/context/getting-started.md

This Ruby code demonstrates how to initialize a Decode::Index object and load all Ruby files from the current directory into it. This index is used for subsequent source code analysis.

```ruby
require 'decode/index'

index = Decode::Index.new

# Load all Ruby files into the index:
index.update(Dir['**/*.rb'])

```

--------------------------------

### Document Ruby code for Decode coverage

Source: https://github.com/socketry/decode/blob/main/context/documentation-coverage.md

Demonstrates how to document classes, modules, methods, and attributes using comments and pragmas like @namespace, @parameter, @returns, and @attribute to satisfy coverage requirements.

```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)
		@email = email
	end
end

# @namespace
module MyGem
	# Provides core functionality.
end

# Process the input data and return results.
# @parameter data [Hash] Input data to process.
# @returns [Array] Processed results.
def process_data(data)
	results = data.map {|item| transform(item)}
	results
end
```

--------------------------------

### Defining a Namespace Module

Source: https://github.com/socketry/decode/blob/main/guides/ruby-documentation/readme.md

Uses the @namespace pragma to mark a module as a container for organization, satisfying documentation coverage requirements without needing detailed descriptions for the module itself.

```ruby
# @namespace
module MyGem
	# This module serves only as a namespace for organizing classes.
	
	class ActualImplementation
		# This class contains the real functionality.
	end
end
```

--------------------------------

### Analyze documentation coverage and symbols via CLI

Source: https://github.com/socketry/decode/blob/main/context/documentation-coverage.md

Use bake tasks to check the ratio of documented definitions, list the codebase structure, or extract all documentation. These commands target specific directories to provide actionable insights into documentation gaps.

```bash
bake decode:index:coverage lib
bake decode:index:coverage app/models
bake decode:index:symbols lib
bake decode:index:documentation lib
```

--------------------------------

### Documenting Ruby Classes and Methods with Decode

Source: https://github.com/socketry/decode/blob/main/guides/ruby-documentation/readme.md

Demonstrates the application of Decode gem documentation standards, including class descriptions, parameter definitions, exception handling, and internal code comments.

```ruby
# Represents a user account in the system.
class User
	# @attribute [String] The user's email address.
	attr_reader :email
	
	# Initialize a new user account.
	# @parameter email [String] The user's email address.
	# @raises [ArgumentError] If email is invalid.
	def initialize(email)
		# Validate email format before assignment:
		raise ArgumentError, "Invalid email format" unless email.match?(/\A[^@\s]+@[^@\s]+\z/)
		
		# Store the normalized email:
		@email = email.downcase.strip
	end
	
	# Authenticate the user with the provided password.
	# @parameter password [String] The password to verify.
	# @returns [bool] True if authentication succeeds.
	def authenticate(password)
		# Hash the password for comparison:
		hashed = hash_password(password)
		
		# Compare against stored hash:
		hashed == @password_hash
	end
	
	# Deactivate the user account.
	# This method sets the user's status to inactive. Use this instead of
	# the deprecated {disable!} method. The account status can be checked
	# using `active?` or by examining the `:active` attribute.
	# @returns [bool] Returns `true` if deactivation was successful.
	def deactivate!
		@active = false
		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
	end
end
```

--------------------------------

### Creating and Managing a Code Index

Source: https://context7.com/socketry/decode/llms.txt

Demonstrates how to initialize a Decode::Index from directory paths or glob patterns. It shows how to populate the index and iterate over parsed definitions.

```ruby
require 'decode/index'

# Create an index from a directory path
index = Decode::Index.for('lib')

# Or create an index from multiple paths and glob patterns
index = Decode::Index.for('lib', 'app/models', 'spec/**/*_spec.rb')

# Alternatively, create an empty index and update it manually
index = Decode::Index.new
paths = Dir.glob('lib/**/*.rb')
index.update(paths)

# Access all parsed definitions
index.definitions.each do |qualified_name, definition|
  puts "#{qualified_name}: #{definition.short_form}"
end
```

--------------------------------

### Integrate documentation coverage into GitHub Actions

Source: https://github.com/socketry/decode/blob/main/context/documentation-coverage.md

Automate documentation quality checks by adding a step to your CI pipeline that runs the coverage bake task.

```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
```

--------------------------------

### Ruby Class and Method Documentation with Decode Pragmas

Source: https://github.com/socketry/decode/blob/main/context/ruby-documentation.md

Demonstrates documenting a Ruby class 'User' including attributes, initialization, authentication, and deactivation. It showcases the use of pragmas like @attribute, @parameter, @raises, and @returns, along with inline comments and Markdown formatting for clarity.

```ruby
# Represents a user account in the system.
class User
	# @attribute [String] The user's email address.
	attr_reader :email
	
	# Initialize a new user account.
	# @parameter email [String] The user's email address.
	# @raises [ArgumentError] If email is invalid.
	def initialize(email)
		# Validate email format before assignment:
		raise ArgumentError, "Invalid email format" unless email.match?(/A[^@\s]+@[^@\s]+\z/)
		
		# Store the normalized email:
		@email = email.downcase.strip
	end
	
	# Authenticate the user with the provided password.
	# @parameter password [String] The password to verify.
	# @returns [bool] True if authentication succeeds.
	def authenticate(password)
		# Hash the password for comparison:
		hashed = hash_password(password)
		
		# Compare against stored hash:
		hashed == @password_hash
	end
	
	# Deactivate the user account.
	# This method sets the user's status to inactive. Use this instead of
	# the deprecated {disable!} method. The account status can be checked
	# using `active?` or by examining the `:active` attribute.
	# @returns [bool] Returns `true` if deactivation was successful.
	def deactivate!
		@active = false
		true
	end
end
```

--------------------------------

### Documenting Attributes and Parameters in Ruby

Source: https://github.com/socketry/decode/blob/main/guides/ruby-documentation/readme.md

Demonstrates the use of @attribute and @parameter pragmas to define data structures and method inputs. These annotations improve readability by explicitly stating expected types.

```ruby
class Person
	# @attribute [String] The person's full name.
	attr_reader :name
	
	# @attribute [Integer] The person's age in years.
	attr_accessor :age
	
	# @attribute [Hash] Configuration settings.
	attr_writer :config
end

# @parameter x [Integer] The x coordinate.
# @parameter y [Integer] The y coordinate.
# @parameter options [Hash] Optional configuration.
def move(x, y, **options)
	# ...
end
```

--------------------------------

### Documenting Blocks and Yields

Source: https://github.com/socketry/decode/blob/main/guides/ruby-documentation/readme.md

Uses the @yields pragma to describe the parameters passed to a block and the expected behavior of the block execution.

```ruby
# @yields {|item| ...} Each item in the collection.
# 	@parameter item [Object] The current item being processed.
def each_item(&block)
	items.each(&block)
end
```

--------------------------------

### Print all definitions from a Decode index

Source: https://github.com/socketry/decode/blob/main/context/getting-started.md

This Ruby snippet iterates through all definitions stored in a Decode::Index object and prints their long-form representation. It's useful for inspecting the contents of the indexed source code.

```ruby
index.definitions.each do |name, symbol|
	puts symbol.long_form
end

```

--------------------------------

### Documenting Blocks and Flow Control in Ruby

Source: https://github.com/socketry/decode/blob/main/context/ruby-documentation.md

Shows how to use @yields to describe block parameters and @throws to document symbol-based flow control.

```ruby
# @yields {|item| ...} Each item in the collection.
# 	@parameter item [Object] The current item being processed.
def each_item(&block)
	items.each(&block)
end

# @throws [:skip] To skip processing this item.
# @throws [:retry] To retry the operation.
def process_item(item)
	throw :skip if item.nil?
	throw :retry if item.invalid?
end
```

--------------------------------

### Lookup a symbol reference in Decode

Source: https://github.com/socketry/decode/blob/main/context/getting-started.md

This Ruby code shows how to parse a string reference (e.g., 'ruby Decode::Index#lookup') into a Decode reference object and then use the index to find the corresponding definition. It demonstrates efficient symbol resolution.

```ruby
# Lookup a specific symbol:
reference = index.languages.parse_reference("ruby Decode::Index#lookup")
definition = index.lookup(reference).first
puts definition.long_form

```

--------------------------------

### Access documentation text from a Decode definition

Source: https://github.com/socketry/decode/blob/main/context/getting-started.md

This Ruby snippet retrieves and prints the documentation text associated with a specific definition object obtained from a Decode::Index. It highlights how to access comments and metadata.

```ruby
lines = definition.documentation.text
puts lines

```

--------------------------------

### Documenting Visibility and Behavior in Ruby

Source: https://github.com/socketry/decode/blob/main/context/ruby-documentation.md

Utilizing pragmas to define method visibility (@public, @private) and behavioral traits like @deprecated and @asynchronous.

```ruby
# @public
def public_method
	# This method is part of the public API.
end

# @private
def internal_helper
	# This method is for internal use only.
end

# @deprecated Use {new_method} instead.
def old_method
	# Legacy implementation
end

# @asynchronous
def fetch_data
	# This method may yield control during execution.
end
```

--------------------------------

### Programmatic Documentation Coverage Check in Ruby

Source: https://context7.com/socketry/decode/llms.txt

This Ruby snippet demonstrates how to programmatically check documentation coverage using the `decode/index` library. It iterates through definitions in an index, counts documented items, and lists definitions that are relevant but lack documentation, including their file path and line number.

```ruby
require 'decode/index'

index = Decode::Index.for('lib')

documented_count = 0
missing = []

index.definitions.each do |name, definition|
  if definition.coverage_relevant?
    if definition.documented?
      documented_count += 1
    else
      missing << definition
    end
  end
end

puts "Documented: #{documented_count}"
puts "Missing: #{missing.size}"
missing.each do |definition|
  location = definition.location
  puts "  - #{definition.qualified_name} (#{location&.path}:#{location&.line})"
end
```

--------------------------------

### Documenting Behavioral Metadata

Source: https://github.com/socketry/decode/blob/main/guides/ruby-documentation/readme.md

Covers the use of visibility modifiers like @public and @private, as well as behavioral markers like @deprecated and @asynchronous.

```ruby
# @deprecated Use {new_method} instead.
def old_method
	# Legacy implementation
end

# @asynchronous
def fetch_data
	# This method may yield control during execution.
end
```

--------------------------------

### Accessing Structured Documentation

Source: https://context7.com/socketry/decode/llms.txt

Shows how to retrieve and filter documentation tags from a definition object, such as parameters and return types.

```ruby
require 'decode/index'

index = Decode::Index.for('lib')
reference = index.languages.parse_reference("ruby Decode::Index#lookup")
definition = index.lookup(reference)

# Access the documentation object
doc = definition.documentation

# Filter for specific tag types
doc.filter(Decode::Comment::Parameter) do |param|
  puts "Parameter: #{param.name} [#{param.type}]"
end

# Check for return type documentation
doc.filter(Decode::Comment::Returns) do |returns|
  puts "Returns: [#{returns.type}] #{returns.text&.join(' ')}"
end
```

--------------------------------

### Resolve Ruby Code References

Source: https://context7.com/socketry/decode/llms.txt

Demonstrates how to resolve various types of Ruby code references, including relative paths, instance methods, class methods, and constants using the Decode::Language::Ruby module.

```ruby
# Relative references (without :: prefix)
relative_ref = Decode::Language::Ruby.reference_for("lookup")
puts relative_ref.relative? # => true

# References with method type indicators
instance_method = Decode::Language::Ruby.reference_for("Index#lookup")
class_method = Decode::Language::Ruby.reference_for("Index.for")
constant = Decode::Language::Ruby.reference_for("Index::VERSION")
```

--------------------------------

### Enumerate Source Definitions and Segments in Ruby

Source: https://context7.com/socketry/decode/llms.txt

This snippet demonstrates how to use the `Source` class from the `decode/index` library to enumerate all definitions and code segments within a Ruby file. It shows how to access definition details like qualified names and documentation status, as well as segment documentation and associated definitions.

```ruby
require 'decode/index'

languages = Decode::Languages.all

# Create a source object for a specific file
source = languages.source_for('lib/decode/index.rb')

# Enumerate all definitions in the file
source.definitions.each do |definition|
  puts "#{definition.class.name.split('::').last}: #{definition.qualified_name}"

  if definition.documented?
    puts "  Documented: Yes"
  else
    puts "  Documented: No"
  end
end
# Output:
# Class: Decode::Index
#   Documented: Yes
# Method: Decode::Index.for
#   Documented: Yes
# Method: Decode::Index#initialize
#   Documented: Yes
# ...

# Enumerate code segments (comment blocks followed by code)
source.segments.each do |segment|
  puts "Segment: #{segment.documentation&.text&.first}"
  puts "  Definitions: #{segment.definitions.map(&:name).join(', ')}"
end
```

--------------------------------

### Overriding Definition Names

Source: https://github.com/socketry/decode/blob/main/guides/ruby-documentation/readme.md

Demonstrates the use of the @name pragma to provide a custom identifier for attributes or methods, overriding the default extraction logic.

```ruby
# @name hostname
# @attribute [String] The server hostname.
attr_reader :server_name
```

--------------------------------

### Parse References from Documentation Text

Source: https://context7.com/socketry/decode/llms.txt

Shows how to extract and parse code references directly from documentation strings using the Decode::Languages registry.

```ruby
# Parse references from documentation text
languages = Decode::Languages.all
ref = languages.parse_reference("ruby Decode::Source#definitions")
```

--------------------------------

### Creating Language References in Ruby

Source: https://context7.com/socketry/decode/llms.txt

This snippet demonstrates the creation of `Language::Reference` objects in Ruby using the `Decode::Language::Ruby` module. It shows how to generate a reference from a string identifier and then access its properties like `identifier`, `path`, and whether it's an absolute reference.

```ruby
require 'decode/language/ruby'

# Create a reference using the Ruby language module
ref = Decode::Language::Ruby.reference_for("Decode::Index#lookup")

puts ref.identifier   # => "Decode::Index#lookup"
puts ref.path.inspect # => [:Decode, :Index, :lookup]
puts ref.absolute?    # => true
```

--------------------------------

### Traversing the Trie Structure

Source: https://context7.com/socketry/decode/llms.txt

Illustrates how to navigate the hierarchical trie structure of the index to explore definitions by their lexical path.

```ruby
require 'decode/index'

index = Decode::Index.for('lib')

# Traverse all definitions in the trie
index.trie.traverse do |path, node, descend|
  if node.values
    node.values.each do |definition|
      puts "#{definition.qualified_name}"
    end
  end
  descend.call
end

# Lookup a specific node by path
node = index.trie.lookup([:Decode, :Index])
```

--------------------------------

### Programmatic RBS Generation in Ruby

Source: https://context7.com/socketry/decode/llms.txt

This Ruby snippet shows how to programmatically generate RBS type signatures using the `Decode::RBS::Generator`. It covers creating an index, instantiating the generator (with an option to include private methods), and generating the RBS output either directly to standard output or capturing it into a string via a `StringIO` object.

```ruby
require 'decode/rbs'

index = Decode::Index.for('lib')

# Create generator (include_private: true to include private methods)
generator = Decode::RBS::Generator.new(include_private: false)

# Generate RBS to stdout
generator.generate(index)

# Or capture to a string
output = StringIO.new
generator.generate(index, output: output)
rbs_content = output.string
```

--------------------------------

### Resolving Symbol References

Source: https://context7.com/socketry/decode/llms.txt

Explains how to use the Index#lookup method to resolve symbols. It covers both absolute references and scope-aware relative lookups.

```ruby
require 'decode/index'

index = Decode::Index.for('lib')

# Parse a reference string into a Reference object
reference = index.languages.parse_reference("ruby Decode::Index#lookup")
definition = index.lookup(reference)

# Lookup a symbol relative to another definition's scope
class_ref = index.languages.parse_reference("ruby Decode::Index")
class_def = index.lookup(class_ref)

# Find 'trie' method relative to Index class
relative_ref = Decode::Language::Ruby.reference_for("trie")
trie_attr = index.lookup(relative_ref, relative_to: class_def)
```

--------------------------------

### Defining Scoped Methods

Source: https://github.com/socketry/decode/blob/main/guides/ruby-documentation/readme.md

Uses the @scope pragma to associate a method with a specific module or class, regardless of its physical location in the source file.

```ruby
# @scope Database
def connect
	# This method belongs to the Database scope.
end
```

=== COMPLETE CONTENT === This response contains all available snippets from this library. No additional content exists. Do not make further requests.