decode 0.22.0 → 0.23.0

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

@@ -3,44 +3,53 @@
 # Released under the MIT License.
 # Copyright, 2020-2024, by Samuel Williams.
 
-require_relative '../reference'
+require_relative "../reference"
 
 module Decode
 	module Language
 		module Ruby
 			# An Ruby-specific reference which can be resolved to zero or more definitions.
 			class Reference < Language::Reference
+				# Create a reference from a constant node.
+				# @parameter node [Prism::Node] The constant node.
+				# @parameter language [Language] The language instance.
 				def self.from_const(node, language)
 					lexical_path = append_const(node)
 					
-					return self.new(node.location.expression.source, language, lexical_path)
+					return self.new(node.location.slice, language, lexical_path)
 				end
 				
+				# Append a constant node to the path.
+				# @parameter node [Prism::Node] The constant node.
+				# @parameter path [Array] The path to append to.
 				def self.append_const(node, path = [])
-					parent, name = node.children
-					
-					if parent and parent.type != :cbase
-						append_const(parent, path)
-					end
-					
 					case node.type
-					when :const
-						if parent && parent.type != :cbase
-							path << ['::', name]
+					when :constant_read_node
+						path << [nil, node.name.to_s]
+					when :constant_path_node
+						if node.parent
+							append_const(node.parent, path)
+							path << ["::", node.name.to_s]
+						else
+							path << [nil, node.name.to_s]
+						end
+					when :call_node
+						# For call nodes like Tuple(...), treat them as constant references
+						if node.receiver.nil?
+							path << [nil, node.name.to_s]
 						else
-							path << [nil, name]
+							append_const(node.receiver, path)
+							path << [".", node.name.to_s]
 						end
-					when :send
-						path << ['#', name]
-					when :cbase
-						# Ignore.
 					else
-						raise ArgumentError, "Could not determine reference for #{node}!"
+						raise ArgumentError, "Could not determine reference for #{node.type}!"
 					end
 					
 					return path
 				end
 				
+				# Split a Ruby identifier into prefix and name components.
+				# @parameter text [String] The text to split.
 				def split(text)
 					text.scan(/(::|\.|#|:)?([^:.#]+)/)
 				end

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

@@ -3,31 +3,38 @@
 # Released under the MIT License.
 # Copyright, 2020-2024, by Samuel Williams.
 
-require_relative '../../segment'
+require_relative "../../segment"
 
 module Decode
 	module Language
 		module Ruby
 			# A Ruby specific code segment.
 			class Segment < Decode::Segment
+				# Initialize a new Ruby segment.
+				# @parameter comments [Array(String)] The comments for this segment.
+				# @parameter language [Language] The language instance.
+				# @parameter node [Prism::Node] The syntax tree node.
+				# @parameter options [Hash] Additional options.
 				def initialize(comments, language, node, **options)
 					super(comments, language, **options)
 					
 					@node = node
-					@expression = node.location.expression
+					@expression = node.location
 				end
 				
 				# The parser syntax tree node.
 				attr :node
 				
+				# Expand the segment to include another node.
+				# @parameter node [Prism::Node] The node to include.
 				def expand(node)
-					@expression = @expression.join(node.location.expression)
+					@expression = @expression.join(node.location)
 				end
 				
 				# The source code trailing the comments.
 				# @returns [String | nil]
 				def code
-					@expression.source
+					@expression.slice
 				end
 			end
 		end

data/lib/decode/language/ruby.rb

@@ -3,12 +3,14 @@
 # Released under the MIT License.
 # Copyright, 2020-2024, by Samuel Williams.
 
-require_relative 'ruby/generic'
+require_relative "ruby/generic"
 
 module Decode
 	module Language
-		# An interface for extracting information from Ruby source code.
+		# Represents an interface for extracting information from Ruby source code.
 		module Ruby
+			# Create a new Ruby language instance.
+			# @returns [Ruby::Generic] A configured Ruby language parser.
 			def self.new
 				Generic.new("ruby")
 			end

data/lib/decode/language.rb

@@ -3,8 +3,8 @@
 # Released under the MIT License.
 # Copyright, 2020-2024, by Samuel Williams.
 
-require_relative 'language/generic'
-require_relative 'language/ruby'
+require_relative "language/generic"
+require_relative "language/ruby"
 
 module Decode
 	# Language specific parsers and definitions.

data/lib/decode/languages.rb

@@ -3,23 +3,27 @@
 # Released under the MIT License.
 # Copyright, 2020-2024, by Samuel Williams.
 
-require_relative 'language/generic'
-require_relative 'language/ruby'
+require_relative "language/generic"
+require_relative "language/ruby"
 
 module Decode
-	# A context for looking up languages based on file extension or name.
+	# Represents a context for looking up languages based on file extension or name.
 	class Languages
+		# Create a new languages context with all supported languages.
+		# @returns [Languages] A languages context with Ruby support enabled.
 		def self.all
 			self.new.tap do |languages|
 				languages.add(Language::Ruby.new)
 			end
 		end
 		
+		# Initialize a new languages context.
 		def initialize
 			@named = {}
 			@extensions = {}
 		end
 		
+		# Freeze the languages context to prevent further modifications.
 		def freeze
 			return unless frozen?
 			
@@ -29,16 +33,23 @@ module Decode
 			super
 		end
 		
+		# Add a language to this context.
+		# @parameter language [Language::Generic] The language to add.
 		def add(language)
+			# Register by name:
 			language.names.each do |name|
 				@named[name] = language
 			end
 			
+			# Register by file extension:
 			language.extensions.each do |extension|
 				@extensions[extension] = language
 			end
 		end
 		
+		# Fetch a language by name, creating a generic language if needed.
+		# @parameter name [String] The name of the language to fetch.
+		# @returns [Language::Generic] The language instance for the given name.
 		def fetch(name)
 			@named.fetch(name) do
 				unless @named.frozen?
@@ -47,6 +58,9 @@ module Decode
 			end
 		end
 		
+		# Create a source object for the given file path.
+		# @parameter path [String] The file system path to create a source for.
+		# @returns [Source | Nil] A source object if the file extension is supported, nil otherwise.
 		def source_for(path)
 			extension = File.extname(path)
 			
@@ -57,9 +71,10 @@ module Decode
 		
 		REFERENCE = /\A(?<name>[a-z]+)?\s+(?<identifier>.*?)\z/
 		
-		# Parse a language agnostic reference:
-		# e.g. `ruby MyModule::MyClass`
-		#
+		# Parse a language agnostic reference.
+		# @parameter text [String] The text to parse (e.g., "ruby MyModule::MyClass").
+		# @parameter default_language [Language::Generic] The default language to use if none specified.
+		# @returns [Language::Reference | Nil] The parsed reference, or nil if parsing fails.
 		def parse_reference(text, default_language: nil)
 			if match = REFERENCE.match(text)
 				language = self.fetch(match[:name]) || default_language
@@ -70,6 +85,10 @@ module Decode
 			end
 		end
 		
+		# Create a reference for the given language and identifier.
+		# @parameter name [String] The name of the language.
+		# @parameter identifier [String] The identifier to create a reference for.
+		# @returns [Language::Reference] The created reference.
 		def reference_for(name, identifier)
 			self.fetch(name).reference_for(identifier)
 		end

data/lib/decode/location.rb

@@ -4,7 +4,9 @@
 # Copyright, 2022-2024, by Samuel Williams.
 
 module Decode
+	# Represents a location in a source file.
 	class Location < Struct.new(:path, :line)
+		# Generate a string representation of the location.
 		def to_s
 			"#{path}:#{line}"
 		end

data/lib/decode/scope.rb

@@ -3,7 +3,7 @@
 # Released under the MIT License.
 # Copyright, 2020-2024, by Samuel Williams.
 
-require_relative 'definition'
+require_relative "definition"
 
 module Decode
 	# An abstract namespace for nesting definitions.

data/lib/decode/segment.rb

@@ -3,7 +3,7 @@
 # Released under the MIT License.
 # Copyright, 2020-2024, by Samuel Williams.
 
-require_relative 'documentation'
+require_relative "documentation"
 
 module Decode
 	# A chunk of code with an optional preceeding comment block.
@@ -14,17 +14,18 @@ module Decode
 	#	~~~
 	#
 	class Segment
+		# Initialize a new segment.
+		# @parameter comments [Array(String)] The preceeding comments.
+		# @parameter language [Language::Generic] The language of the code.
 		def initialize(comments, language)
 			@comments = comments
 			@language = language
 		end
 		
-		# The preceeding comments.
-		# @attribute [Array(String)]
+		# @attribute [Array(String)] The preceeding comments.
 		attr :comments
 		
-		# The language of the code attached to this segment.
-		# @attribute [Language::Generic]
+		# @attribute [Language::Generic] The language of the code attached to this segment.
 		attr :language
 		
 		# An interface for accsssing the documentation of the definition.

data/lib/decode/source.rb

@@ -3,11 +3,14 @@
 # Released under the MIT License.
 # Copyright, 2020-2024, by Samuel Williams.
 
-require_relative 'language'
+require_relative "language"
 
 module Decode
 	# Represents a source file in a specific language.
 	class Source
+		# Initialize a new source file.
+		# @parameter path [String] The file-system path to the source file.
+		# @parameter language [Language::Generic] The language parser to use.
 		def initialize(path, language)
 			@path = path
 			@buffer = nil
@@ -15,10 +18,11 @@ module Decode
 		end
 		
 		# The path of the source file.
-		# @attribute [String] A file-system path.
+		# @attribute [String] A file-system path to the source file.
 		attr :path
 		
 		# The relative path of the source, if it is known.
+		# @returns [String] The relative path or the full path if relative path is unknown.
 		def relative_path
 			if @path.respond_to?(:relative_path)
 				@path.relative_path
@@ -28,11 +32,11 @@ module Decode
 		end
 		
 		# The language of the source file.
-		# @attribute [Language::Generic]
+		# @attribute [Language::Generic] The language parser for this source.
 		attr :language
 		
 		# Read the source file into an internal buffer/cache.
-		# @returns [String]
+		# @returns [String] The contents of the source file.
 		def read
 			@buffer ||= File.read(@path).freeze
 		end
@@ -57,6 +61,10 @@ module Decode
 			@language.segments_for(self, &block)
 		end
 		
+		# Generate code representation with optional index for link resolution.
+		# @parameter index [Index] Optional index for resolving links.
+		# @parameter relative_to [Definition] Optional definition to resolve relative references.
+		# @returns [String] The formatted code representation.
 		def code(index = nil, relative_to: nil)
 			@language.code_for(self.read, index, relative_to: relative_to)
 		end

data/lib/decode/syntax/link.rb

@@ -3,11 +3,16 @@
 # Released under the MIT License.
 # Copyright, 2020-2024, by Samuel Williams.
 
-require_relative 'match'
+require_relative "match"
 
 module Decode
+	# Provides syntax rewriting and linking functionality.
 	module Syntax
+		# Represents a link to a definition in the documentation.
 		class Link < Match
+			# Initialize a new link.
+			# @parameter range [Range] The range of text to link.
+			# @parameter definition [Definition] The definition to link to.
 			def initialize(range, definition)
 				@definition = definition
 				
@@ -16,6 +21,9 @@ module Decode
 			
 			attr :definition
 			
+			# Apply the link to the output.
+			# @parameter output [String] The output to append to.
+			# @parameter rewriter [Rewriter] The rewriter instance.
 			def apply(output, rewriter)
 				output << rewriter.link_to(
 					@definition,

data/lib/decode/syntax/match.rb

@@ -5,29 +5,41 @@
 
 module Decode
 	module Syntax
+		# Represents a match in the source text for syntax rewriting.
 		class Match
+			# Initialize a new match.
+			# @parameter range [Range] The range of text this match covers.
 			def initialize(range)
 				@range = range
 			end
 			
 			attr :range
 			
+			# Apply the match to extract text from source.
+			# @parameter source [String] The source text.
 			def apply(source)
 				return source[range]
 			end
 			
+			# Compare matches by their starting position.
+			# @parameter other [Match] The other match to compare.
 			def <=> other
 				@range.min <=> other.range.min
 			end
 			
+			# Get the starting offset of this match.
 			def offset
 				@range.min
 			end
 			
+			# Get the size of this match.
 			def size
 				@range.size
 			end
 			
+			# Apply the match to the output.
+			# @parameter output [String] The output to append to.
+			# @parameter rewriter [Rewriter] The rewriter instance.
 			def apply(output, rewriter)
 				output << rewriter.text_for(@range)
 				

data/lib/decode/syntax/rewriter.rb

@@ -5,7 +5,10 @@
 
 module Decode
 	module Syntax
+		# Provides text rewriting functionality with match-based substitutions.
 		class Rewriter
+			# Initialize a new rewriter.
+			# @parameter text [String] The text to rewrite.
 			def initialize(text)
 				@text = text
 				@matches = []
@@ -15,6 +18,8 @@ module Decode
 			
 			attr :matches
 			
+			# Add a match to the rewriter.
+			# @parameter match [Match] The match to add.
 			def << match
 				@matches << match
 			end
@@ -24,6 +29,8 @@ module Decode
 				@text[range]
 			end
 			
+			# Apply all matches to generate the rewritten output.
+			# @parameter output [Array] The output array to append to.
 			def apply(output = [])
 				offset = 0
 				
@@ -47,6 +54,9 @@ module Decode
 				return output
 			end
 			
+			# Generate a link to a definition.
+			# @parameter definition [Definition] The definition to link to.
+			# @parameter text [String] The text to display for the link.
 			def link_to(definition, text)
 				"[#{text}]"
 			end

data/lib/decode/trie.rb

@@ -3,36 +3,40 @@
 # Released under the MIT License.
 # Copyright, 2020-2024, by Samuel Williams.
 
-require_relative 'source'
+require_relative "source"
 
 module Decode
-	# A prefix-trie data structure for fast lexical lookups.
+	# Represents a prefix-trie data structure for fast lexical lookups.
 	class Trie
-		# A single node in the trie.
+		# Represents a single node in the trie.
 		class Node
+			# Initialize a new trie node.
 			def initialize
 				@values = nil
 				@children = Hash.new
 			end
 			
+			# Generate a string representation of this node.
+			# @returns [String] A formatted string showing the number of children.
 			def inspect
 				"#<#{self.class} #{@children.size} children>"
 			end
 
+			# Generate a string representation of the node.
 			alias to_s inspect
 
 			# A mutable array of all values that terminate at this node.
-			# @attribute [Array]
+			# @attribute [Array | Nil] The values stored at this node, or nil if no values.
 			attr_accessor :values
 			
 			# A hash table of all children nodes, indexed by name.
-			# @attribute [Hash(String, Node)]
+			# @attribute [Hash(String, Node)] Child nodes indexed by their path component.
 			attr :children
 			
 			# Look up a lexical path starting at this node.
-			#
 			# @parameter path [Array(String)] The path to resolve.
-			# @returns [Node | Nil]
+			# @parameter index [Integer] The current index in the path (used for recursion).
+			# @returns [Node | Nil] The node at the specified path, or nil if not found.
 			def lookup(path, index = 0)
 				if index < path.size
 					if child = @children[path[index]]
@@ -45,13 +49,11 @@ module Decode
 			
 			# Traverse the trie from this node.
 			# Invoke `descend.call` to traverse the children of the current node.
-			#
 			# @parameter path [Array(String)] The current lexical path.
-			#
-			# @block {|path, node, descend| descend.call}
-			# @yield path [Array(String)] The current lexical path.
-			# @yield node [Node] The current node which is being traversed.
-			# @yield descend [Proc] The recursive method for traversing children.
+			# @yields {|path, node, descend| ...} Called for each node during traversal.
+			#   @parameter path [Array(String)] The current lexical path.
+			#   @parameter node [Node] The current node which is being traversed.
+			#   @parameter descend [Proc] The recursive method for traversing children.
 			def traverse(path = [], &block)
 				yield(path, self, ->{
 					@children.each do |name, node|
@@ -67,35 +69,36 @@ module Decode
 		end
 		
 		# The root of the trie.
-		# @attribute [Node]
+		# @attribute [Node] The root node of the trie structure.
 		attr :root
 		
 		# Insert the specified value at the given path into the trie.
 		# @parameter path [Array(String)] The lexical path where the value will be inserted.
-		# @parameter value [Object] The value to insert.
+		# @parameter value [Object] The value to insert at the specified path.
 		def insert(path, value)
 			node = @root
 			
+			# Navigate to the target node, creating nodes as needed:
 			path.each do |key|
 				node = (node.children[key] ||= Node.new)
 			end
 			
+			# Add the value to the target node:
 			(node.values ||= []) << value
 		end
 		
 		# Lookup the values at the specified path.
-		#
 		# @parameter path [Array(String)] The lexical path which contains the values.
-		# @returns [Array(Object) | Nil] The values that existed (or not) at the specified path.
+		# @returns [Node | Nil] The node at the specified path, or nil if not found.
 		def lookup(path)
 			@root.lookup(path)
 		end
 		
 		# Enumerate all lexical scopes under the specified path.
-		#
-		# @block {|path, values| ...}
-		# @yield path [Array(String)] The lexical path.
-		# @yield values [Array(Object)] The values that exist at the given path.
+		# @parameter path [Array(String)] The starting path to enumerate from.
+		# @yields {|path, values| ...} Called for each path with values.
+		#   @parameter path [Array(String)] The lexical path.
+		#   @parameter values [Array(Object) | Nil] The values that exist at the given path.
 		def each(path = [], &block)
 			if node = @root.lookup(path)
 				node.traverse do |path, node, descend|
@@ -106,8 +109,10 @@ module Decode
 			end
 		end
 		
-		# Traverse the trie.
+		# Traverse the trie starting from the specified path.
 		# See {Node#traverse} for details.
+		# @parameter path [Array(String)] The starting path to traverse from.
+		# @yields {|path, node, descend| ...} Called for each node during traversal.
 		def traverse(path = [], &block)
 			if node = @root.lookup(path)
 				node.traverse(&block)

data/lib/decode/version.rb

@@ -4,5 +4,5 @@
 # Copyright, 2020-2024, by Samuel Williams.
 
 module Decode
-	VERSION = "0.22.0"
+	VERSION = "0.23.0"
 end

metadata

@@ -1,11 +1,10 @@
 --- !ruby/object:Gem::Specification
 name: decode
 version: !ruby/object:Gem::Version
-  version: 0.22.0
+  version: 0.23.0
 platform: ruby
 authors:
 - Samuel Williams
-autorequire:
 bindir: bin
 cert_chain:
 - |
@@ -37,10 +36,10 @@ cert_chain:
   Q2K9NVun/S785AP05vKkXZEFYxqG6EW012U4oLcFl5MySFajYXRYbuUpH6AY+HP8
   voD0MPg1DssDLKwXyt1eKD/+Fq0bFWhwVM/1XiAXL7lyYUyOq24KHgQ2Csg=
   -----END CERTIFICATE-----
-date: 2024-08-17 00:00:00.000000000 Z
+date: 1980-01-02 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
-  name: parser
+  name: prism
   requirement: !ruby/object:Gem::Requirement
     requirements:
     - - ">="
@@ -53,13 +52,14 @@ dependencies:
     - - ">="
       - !ruby/object:Gem::Version
         version: '0'
-description:
-email:
 executables: []
 extensions: []
 extra_rdoc_files: []
 files:
 - bake/decode/index.rb
+- context/coverage.md
+- context/getting-started.md
+- context/ruby-documentation.md
 - lib/decode.rb
 - lib/decode/comment/attribute.rb
 - lib/decode/comment/node.rb
@@ -80,6 +80,7 @@ files:
 - lib/decode/language/generic.rb
 - lib/decode/language/reference.rb
 - lib/decode/language/ruby.rb
+- lib/decode/language/ruby/alias.rb
 - lib/decode/language/ruby/attribute.rb
 - lib/decode/language/ruby/block.rb
 - lib/decode/language/ruby/call.rb
@@ -113,7 +114,6 @@ metadata:
   documentation_uri: https://ioquatix.github.io/decode/
   funding_uri: https://github.com/sponsors/ioquatix/
   source_code_uri: https://github.com/ioquatix/decode.git
-post_install_message:
 rdoc_options: []
 require_paths:
 - lib
@@ -121,15 +121,14 @@ required_ruby_version: !ruby/object:Gem::Requirement
   requirements:
   - - ">="
     - !ruby/object:Gem::Version
-      version: '3.1'
+      version: '3.2'
 required_rubygems_version: !ruby/object:Gem::Requirement
   requirements:
   - - ">="
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 3.5.11
-signing_key:
+rubygems_version: 3.6.7
 specification_version: 4
 summary: Code analysis for documentation generation.
 test_files: []