decode 0.22.0 → 0.23.0

data/context/ruby-documentation.md

@@ -0,0 +1,363 @@
+# Ruby Documentation
+
+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.
+
+## Documentation Guidelines
+
+### Writing Style and Format
+
+#### 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.
+
+#### 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.
+
+#### 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`
+
+#### Examples
+
+```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 [Boolean] 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 [Boolean] 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
+```
+
+**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)
+- `:active` - Formats the symbol in monospace (backticks for code formatting)
+- `true` - Formats the boolean value in monospace (backticks for code formatting)
+
+### 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.
+
+#### Simple Attributes and Methods
+
+For extremely simple attributes and methods where the name clearly indicates the purpose, avoid redundant descriptions. Instead, attach the description directly to the `@attribute` pragma:
+
+```ruby
+# Good - concise and clear:
+# @attribute [String] The name of the parameter.
+attr :name
+
+# @attribute [String] The type of the parameter.
+attr :type
+
+# Avoid - redundant descriptions:
+# The name of the parameter.
+# @attribute [String] The parameter name.
+attr :name
+```
+
+This approach keeps documentation concise while still providing essential type information.
+
+## Type Signatures
+
+Type signatures are used to specify the expected types of parameters, return values, and attributes in Ruby code. They help clarify the intended use of methods and improve code readability.
+
+### Primitive Types
+
+- `String`: Represents a sequence of characters.
+- `Integer`: Represents whole numbers.
+- `Float`: Represents decimal numbers.
+- `Boolean`: Represents true or false values.
+- `Symbol`: Represents a name or identifier.
+
+### Composite Types
+
+- `Array(Type)`: Represents an ordered collection of items.
+- `Hash(KeyType, ValueType)`: Represents a collection of key-value pairs.
+- `Interface(:method1, :method2)`: Represents a contract that a class must implement, specifying required methods.
+- `Type | Nil`: Represents an optional type.
+
+## Supported Pragmas
+
+### Type and Return Value Documentation
+
+#### `@attribute [Type] Description.`
+
+Documents class attributes, instance variables, and `attr_*` declarations. Prefer to have one attribute per line for clarity.
+
+```ruby
+# Represents a person with basic attributes.
+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 name [Type] Description.`
+
+Documents method parameters with their types and descriptions.
+
+```ruby
+# @parameter x [Integer] The x coordinate.
+# @parameter y [Integer] The y coordinate.
+# @parameter options [Hash] Optional configuration.
+def move(x, y, **options)
+	# ...
+end
+```
+
+#### `@option :key [Type] Description.`
+
+Documents hash options (keyword arguments).
+
+```ruby
+# @parameter user [User] The user object.
+# @option :cached [Boolean] Whether to cache the result.
+# @option :timeout [Integer] Request timeout in seconds.
+def fetch_user_data(user, **options)
+	# ...
+end
+```
+
+#### `@returns [Type] Description.`
+
+Documents return values.
+
+```ruby
+# @returns [String] The formatted user name.
+def full_name
+	"#{first_name} #{last_name}"
+end
+
+# @returns [Array(User)] All active users.
+def active_users
+	users.select(&:active?)
+end
+```
+
+#### `@raises [Exception] Description.`
+
+Documents exceptions that may be raised.
+
+```ruby
+# @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
+```
+
+#### `@throws [:symbol] Description.`
+
+Documents symbols that may be thrown (used with `catch`/`throw`).
+
+```ruby
+# @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
+```
+
+### Block Documentation
+
+#### `@yields {|param| ...} Description.`
+
+Documents block parameters and behavior.
+
+```ruby
+# @yields {|item| ...} Each item in the collection.
+#   @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.
+def each_user_with_index(&block)
+	users.each_with_index(&block)
+end
+```
+
+### Visibility and Access Control
+
+#### `@public`
+
+Explicitly marks a method as public (useful for documentation clarity).
+
+```ruby
+# @public
+def public_method
+	# This method is part of the public API.
+end
+```
+
+#### `@private`
+
+Marks a method as private (for documentation purposes).
+
+```ruby
+# @private
+def internal_helper
+	# This method is for internal use only.
+end
+```
+
+### Behavioral Documentation
+
+#### `@deprecated Description.`
+
+Marks methods as deprecated with migration guidance.
+
+```ruby
+# @deprecated Use {new_method} instead.
+def old_method
+	# Legacy implementation
+end
+```
+
+#### `@asynchronous`
+
+Indicates that a method may yield control.
+
+```ruby
+# @asynchronous
+def fetch_data
+	# This method may yield control during execution.
+end
+```
+
+### Namespace Documentation
+
+#### `@namespace`
+
+Marks a module as serving only as a namespace, achieving 100% documentation coverage without requiring detailed documentation of empty container modules.
+
+```ruby
+# @namespace
+module MyGem
+	# This module serves only as a namespace for organizing classes.
+	
+	class ActualImplementation
+		# This class contains the real functionality.
+	end
+end
+```
+
+**Why use `@namespace`?**
+- Achieves 100% documentation coverage without redundant documentation.
+- Clearly indicates that a module is purely organizational.
+- Avoids documenting modules that exist only to group related classes.
+- Maintains clean, focused documentation on actual functionality.
+
+**When to use `@namespace`:**
+- Root gem modules that only contain other classes/modules.
+- Organizational modules with no methods or meaningful state.
+- Modules that exist purely for constant scoping.
+- Any module where documentation would add no value.
+
+**Note:** This pragma is treated as a form of documentation by the Decode gem, satisfying coverage requirements while keeping the codebase clean.
+
+## Special Pragmas for Code Structure
+
+### `@name custom_name`
+
+Overrides the default name extraction for attributes or methods.
+
+```ruby
+# @name hostname
+# @attribute [String] The server hostname.
+attr_reader :server_name
+```
+
+### `@scope Module::Name`
+
+Defines scope for definitions that should be associated with a specific module.
+
+```ruby
+# @scope Database
+def connect
+	# This method belongs to the Database scope.
+end
+```

data/lib/decode/comment/attribute.rb

@@ -3,9 +3,10 @@
 # Released under the MIT License.
 # Copyright, 2020-2024, by Samuel Williams.
 
-require_relative 'tag'
+require_relative "tag"
 
 module Decode
+	# Represents comment parsing and processing functionality.
 	module Comment
 		# Describes an attribute type.
 		#
@@ -14,6 +15,9 @@ module Decode
 		class Attribute < Tag
 			PATTERN = /\A\[(?<type>.*?)\](\s+(?<details>.*?))?\Z/
 			
+			# Build an attribute from a directive and match.
+			# @parameter directive [String] The original directive text.
+			# @parameter match [MatchData] The regex match data.
 			def self.build(directive, match)
 				node = self.new(directive, match[:type])
 				
@@ -24,14 +28,16 @@ module Decode
 				return node
 			end
 			
+			# Initialize a new attribute.
+			# @parameter directive [String] The original directive text.
+			# @parameter type [String] The type of the attribute.
 			def initialize(directive, type)
 				super(directive)
 				
 				@type = type
 			end
 			
-			# The type of the attribute.
-			# @attribute [String]
+			# @attribute [String] The type of the attribute.
 			attr :type
 		end
 	end

data/lib/decode/comment/node.rb

@@ -5,6 +5,7 @@
 
 module Decode
 	module Comment
+		# Represents a node in a comment tree structure.
 		class Node
 			# Initialize the node.
 			# @parameter children [Array(Node) | Nil]
@@ -26,8 +27,7 @@ module Decode
 				@children << child
 			end
 			
-			# Any children of this node.
-			# @attribute [Array(Node | Text) | Nil]
+			# @attribute [Array(Node | Text) | Nil] Any children of this node.
 			attr :children
 			
 			# Enumerate all non-text children nodes.
@@ -39,6 +39,8 @@ module Decode
 				end
 			end
 			
+			# Filter children nodes by class type.
+			# @parameter klass [Class] The class to filter by.
 			def filter(klass)
 				return to_enum(:filter, klass) unless block_given?
 				

data/lib/decode/comment/option.rb

@@ -3,7 +3,7 @@
 # Released under the MIT License.
 # Copyright, 2024, by Samuel Williams.
 
-require_relative 'parameter'
+require_relative "parameter"
 
 module Decode
 	module Comment

data/lib/decode/comment/parameter.rb

@@ -3,17 +3,21 @@
 # Released under the MIT License.
 # Copyright, 2020-2024, by Samuel Williams.
 
-require_relative 'tag'
+require_relative "tag"
 
 module Decode
 	module Comment
-		# Describes a named method parameter.
+		# Represents a named method parameter.
 		#
 		# - `@parameter age [Float] The users age.`
 		#
 		class Parameter < Tag
 			PATTERN = /\A(?<name>.*?)\s+\[(?<type>.*?)\](\s+(?<details>.*?))?\Z/
 			
+			# Build a parameter from a directive and regex match.
+			# @parameter directive [String] The original directive text.
+			# @parameter match [MatchData] The regex match data containing name, type, and details.
+			# @returns [Parameter] A new parameter object.
 			def self.build(directive, match)
 				node = self.new(directive, match[:name], match[:type])
 				
@@ -24,6 +28,10 @@ module Decode
 				return node
 			end
 			
+			# Initialize a new parameter.
+			# @parameter directive [String] The original directive text.
+			# @parameter name [String] The name of the parameter.
+			# @parameter type [String] The type of the parameter.
 			def initialize(directive, name, type)
 				super(directive)
 				
@@ -31,12 +39,10 @@ module Decode
 				@type = type
 			end
 			
-			# The name of the parameter.
-			# @attribute [String]
+			# @attribute [String] The name of the parameter.
 			attr :name
 			
-			# The type of the attribute.
-			# @attribute [String]
+			# @attribute [String] The type of the parameter.
 			attr :type
 		end
 	end

data/lib/decode/comment/pragma.rb

@@ -3,7 +3,7 @@
 # Released under the MIT License.
 # Copyright, 2020-2024, by Samuel Williams.
 
-require_relative 'tag'
+require_relative "tag"
 
 module Decode
 	module Comment
@@ -15,10 +15,19 @@ module Decode
 		# - `@asynchronous This method may yield.`
 		#
 		class Pragma < Tag
+			# Parse a pragma directive from text.
+			# @parameter directive [String] The directive name.
+			# @parameter text [String] The directive text.
+			# @parameter lines [Array(String)] The remaining lines.
+			# @parameter tags [Array(Tag)] The collection of tags.
+			# @parameter level [Integer] The indentation level.
 			def self.parse(directive, text, lines, tags, level = 0)
 				self.build(directive, text)
 			end
 			
+			# Build a pragma from a directive and text.
+			# @parameter directive [String] The directive name.
+			# @parameter text [String] The directive text.
 			def self.build(directive, text)
 				node = self.new(directive)
 				
@@ -29,6 +38,8 @@ module Decode
 				return node
 			end
 			
+			# Initialize a new pragma.
+			# @parameter directive [String] The directive name.
 			def initialize(directive)
 				super(directive)
 			end

data/lib/decode/comment/raises.rb

@@ -3,7 +3,7 @@
 # Released under the MIT License.
 # Copyright, 2020-2024, by Samuel Williams.
 
-require_relative 'attribute'
+require_relative "attribute"
 
 module Decode
 	module Comment

data/lib/decode/comment/returns.rb

@@ -3,14 +3,13 @@
 # Released under the MIT License.
 # Copyright, 2020-2024, by Samuel Williams.
 
-require_relative 'attribute'
+require_relative "attribute"
 
 module Decode
 	module Comment
-		# Describes a return value.
-		#
-		# - `@returns [Integer] The person's age.`
+		# Represents a return value.
 		#
+		# Example: `@returns [Integer] The person's age.`
 		class Returns < Attribute
 		end
 	end

data/lib/decode/comment/tag.rb

@@ -3,15 +3,24 @@
 # Released under the MIT License.
 # Copyright, 2020-2024, by Samuel Williams.
 
-require_relative 'node'
+require_relative "node"
 
 module Decode
 	module Comment
+		# Represents a documentation tag parsed from a comment directive.
 		class Tag < Node
+			# Match text against the tag pattern.
+			# @parameter text [String] The text to match.
 			def self.match(text)
 				self::PATTERN.match(text)
 			end
 			
+			# Parse a tag from a directive and text.
+			# @parameter directive [String] The directive name.
+			# @parameter text [String] The directive 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)
 				if match = self.match(text)
 					node = self.build(directive, match)
@@ -27,12 +36,13 @@ module Decode
 				end
 			end
 			
+			# Initialize a new tag.
+			# @parameter directive [String] The directive that generated the tag.
 			def initialize(directive)
 				@directive = directive
 			end
 			
-			# The directive that generated the tag.
-			# @attribute [String]
+			# @attribute [String] The directive that generated the tag.
 			attr :directive
 		end
 	end

data/lib/decode/comment/tags.rb

@@ -3,11 +3,14 @@
 # Released under the MIT License.
 # Copyright, 2020-2024, by Samuel Williams.
 
-require_relative 'text'
+require_relative "text"
 
 module Decode
 	module Comment
+		# Represents a collection of documentation tags and their parsing logic.
 		class Tags
+			# Build a tags parser with directive mappings.
+			# @parameter block [Proc] A block that yields the directives hash.
 			def self.build
 				directives = Hash.new
 				
@@ -16,16 +19,25 @@ module Decode
 				return self.new(directives)
 			end
 			
+			# Initialize a new tags parser.
+			# @parameter directives [Hash(String, Class)] The directive mappings.
 			def initialize(directives)
 				@directives = directives
 			end
 			
+			# Check if a line has valid indentation for the given level.
+			# @parameter line [String] The line to check.
+			# @parameter level [Integer] The expected indentation level.
 			def valid_indentation?(line, level)
-				line.start_with?('  ' * level) || line.start_with?("\t" * level)
+				line.start_with?("  " * level) || line.start_with?("\t" * level)
 			end
 			
 			PATTERN = /\A\s*@(?<directive>.*?)(\s+(?<remainder>.*?))?\Z/
 			
+			# Parse documentation tags from lines.
+			# @parameter lines [Array(String)] The lines to parse.
+			# @parameter level [Integer] The indentation level.
+			# @parameter block [Proc] A block to yield parsed tags to.
 			def parse(lines, level = 0, &block)
 				while line = lines.first
 					# Is it at the right indentation level:
@@ -52,6 +64,9 @@ module Decode
 				end
 			end
 			
+			# Ignore lines at the specified indentation level.
+			# @parameter lines [Array(String)] The lines to ignore.
+			# @parameter level [Integer] The indentation level.
 			def ignore(lines, level = 0)
 				if line = lines.first
 					# Is it at the right indentation level:

data/lib/decode/comment/text.rb

@@ -3,18 +3,21 @@
 # Released under the MIT License.
 # Copyright, 2020-2024, by Samuel Williams.
 
-require_relative 'node'
+require_relative "node"
 
 module Decode
 	module Comment
 		# A structured comment.
 		class Text
+			# Initialize a new text node.
+			# @parameter line [String] The text content.
 			def initialize(line)
 				@line = line
 			end
 			
 			attr :line
 			
+			# Traverse the text node.
 			def traverse
 			end
 		end

data/lib/decode/comment/throws.rb

@@ -3,7 +3,7 @@
 # Released under the MIT License.
 # Copyright, 2020-2024, by Samuel Williams.
 
-require_relative 'attribute'
+require_relative "attribute"
 
 module Decode
 	module Comment