decode 0.22.0 → 0.23.0

data/lib/decode/comment/yields.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,6 +15,9 @@ module Decode
 		class Yields < Tag
 			PATTERN = /\A(?<block>{.*?})(\s+(?<details>.*?))?\Z/
 			
+			# Build a yields tag from a directive and match.
+			# @parameter directive [String] The directive name.
+			# @parameter match [MatchData] The regex match data.
 			def self.build(directive, match)
 				node = self.new(directive, match[:block])
 				
@@ -25,6 +28,9 @@ module Decode
 				return node
 			end
 			
+			# Initialize a new yields tag.
+			# @parameter directive [String] The directive name.
+			# @parameter block [String] The block signature.
 			def initialize(directive, block)
 				super(directive)
 				

data/lib/decode/definition.rb

@@ -3,76 +3,106 @@
 # Released under the MIT License.
 # Copyright, 2020-2024, by Samuel Williams.
 
-require_relative 'location'
+require_relative "location"
 
 module Decode
 	# A symbol with attached documentation.
 	class Definition
 		# Initialize the symbol.
-		# @parameter name [Symbol] The name of the definition.
+		# @parameter path [Symbol | Array(Symbol)] The path of the definition relatve to the parent.
 		# @parameter parent [Symbol] The parent lexical scope.
 		# @parameter language [Language] The language in which the symbol is defined in.
 		# @parameter comments [Array(String)] The comments associated with the definition.
-		def initialize(name, parent: nil, language: parent.language, comments: nil)
-			@name = name
+		# @parameter source [Source] The source file containing this definition.
+		def initialize(path, parent: nil, language: parent&.language, comments: nil, visibility: :public, source: parent&.source)
+			@path = Array(path).map(&:to_sym)
 			
 			@parent = parent
 			@language = language
+			@source = source
 			
 			@comments = comments
+			@visibility = visibility
 			
-			@path = nil
+			@full_path = nil
 			@qualified_name = nil
+			@nested_name = nil
 		end
 		
+		# Generate a debug representation of the definition.
 		def inspect
 			"\#<#{self.class} #{qualified_name}>"
 		end
 		
+		# Generate a string representation of the definition.
 		alias to_s inspect
-
+		
 		# The symbol name.
 		# e.g. `:Decode`.
 		# @attribute [Symbol]
-		attr :name
+		def name
+			@path.last
+		end
+		
+		# @attribute [Array(Symbol)] The path to the definition, relative to the parent.
+		attr :path
+		
+		# The full path to the definition.
+		def full_path
+			@full_path ||= begin
+				if @parent
+					@parent.full_path + @path
+				else
+					@path
+				end
+			end
+		end
+		
+		# The lexical path to the definition (full path including all namespaces).
+		# @returns [Array(Symbol)] The complete path from root to this definition.
+		alias lexical_path full_path
 		
-		# The parent definition, defining lexical scope.
-		# @attribute [Definition | Nil]
+		# @attribute [Definition | Nil] The parent definition, defining lexical scope.
 		attr :parent
 		
-		# The language the symbol is defined within.
-		# @attribute [Language::Generic]
+		# @attribute [Language::Generic] The language the symbol is defined within.
 		attr :language
 		
-		# The comment lines which directly preceeded the definition.
-		# @attribute [Array(String)]
+		# @attribute [Source | Nil] The source file containing this definition.
+		attr :source
+		
+		# @attribute [Array(String)] The comment lines which directly preceeded the definition.
 		attr :comments
 		
 		# Whether the definition is considered part of the public interface.
-		#
 		# This is used to determine whether the definition should be documented for coverage purposes.
-		#
-		# @returns [Boolean]
+		# @returns [Boolean] True if the definition is public.
 		def public?
 			true
 		end
 		
+		# Whether the definition has documentation.
+		# @returns [Boolean] True if the definition has non-empty comments.
+		def documented?
+			@comments&.any?
+		end
+		
 		# The qualified name is an absolute name which includes any and all namespacing.
 		# @returns [String]
 		def qualified_name
 			@qualified_name ||= begin
 				if @parent
-					@parent.qualified_name + self.nested_name
+					[@parent.qualified_name, self.nested_name].join("::")
 				else
-					@name.to_s
+					self.nested_name
 				end
 			end
 		end
 		
-		# The name of this definition plus the nesting prefix.
+		# The name relative to the parent.
 		# @returns [String]
 		def nested_name
-			"::#{@name}"
+			@nested_name ||= "#{@path.join("::")}"
 		end
 		
 		# Does the definition name match the specified prefix?
@@ -86,28 +116,6 @@ module Decode
 			raise ArgumentError, "Unable to convert #{self} into #{kind}!"
 		end
 		
-		# The lexical scope as an array of names.
-		# e.g. `[:Decode, :Definition]`
-		# @returns [Array]
-		def path
-			if @path
-				# Cached version:
-				@path
-			elsif @parent
-				# Merge with parent:
-				@path = [*@parent.path, *path_name].freeze
-			else
-				# At top:
-				@path = path_name.freeze
-			end
-		end
-		
-		def path_name
-			[@name]
-		end
-		
-		alias lexical_path path
-		
 		# A short form of the definition.
 		# e.g. `def short_form`.
 		#
@@ -173,5 +181,9 @@ module Decode
 		def location
 			nil
 		end
+		
+		# The visibility of the definition.
+		# @attribute [Symbol] :public, :private, :protected
+		attr_accessor :visibility
 	end
 end

data/lib/decode/documentation.rb

@@ -3,17 +3,17 @@
 # Released under the MIT License.
 # Copyright, 2020-2024, by Samuel Williams.
 
-require_relative 'comment/node'
+require_relative "comment/node"
 
-require_relative 'comment/tags'
-require_relative 'comment/attribute'
-require_relative 'comment/parameter'
-require_relative 'comment/option'
-require_relative 'comment/pragma'
-require_relative 'comment/raises'
-require_relative 'comment/returns'
-require_relative 'comment/throws'
-require_relative 'comment/yields'
+require_relative "comment/tags"
+require_relative "comment/attribute"
+require_relative "comment/parameter"
+require_relative "comment/option"
+require_relative "comment/pragma"
+require_relative "comment/raises"
+require_relative "comment/returns"
+require_relative "comment/throws"
+require_relative "comment/yields"
 
 module Decode
 	# Structured access to a set of comment lines.
@@ -31,12 +31,10 @@ module Decode
 			end
 		end
 		
-		# The underlying comments from which the documentation is extracted.
-		# @attribute [Array(String)]
+		# @attribute [Array(String)] The underlying comments from which the documentation is extracted.
 		attr :comments
 		
-		# The language in which the documentation was extracted from.
-		# @attribute [Language::Generic]
+		# @attribute [Language::Generic] The language in which the documentation was extracted from.
 		attr :language
 	end
 end

data/lib/decode/index.rb

@@ -3,90 +3,105 @@
 # Released under the MIT License.
 # Copyright, 2020-2024, by Samuel Williams.
 
-require_relative 'source'
-require_relative 'trie'
+require_relative "source"
+require_relative "trie"
 
-require_relative 'languages'
+require_relative "languages"
 
 module Decode
-	# A list of definitions organised for quick lookup and lexical enumeration.
+	# Represents a list of definitions organised for quick lookup and lexical enumeration.
 	class Index
 		# Initialize an empty index.
+		# @parameter languages [Languages] The languages to support in this index.
 		def initialize(languages = Languages.all)
+			# Initialize with supported languages:
 			@languages = languages
 			
+			# Initialize storage for sources and definitions:
 			@sources = {}
 			@definitions = {}
 			
-			# This is essentially a prefix tree:
+			# Create a prefix tree for efficient lookups:
 			@trie = Trie.new
 		end
 		
+		# Generate a string representation of this index.
+		# @returns [String] A formatted string showing the number of definitions.
 		def inspect
 			"#<#{self.class} #{@definitions.size} definition(s)>"
 		end
 
+		# Generate a string representation of the index.
 		alias to_s inspect
 
 		# All supported languages for this index.
-		# @attribute [Languages]
+		# @attribute [Languages] The languages this index can parse.
 		attr :languages
 		
 		# All source files that have been parsed.
-		# @attribute [Array(Source)]
+		# @attribute [Hash(String, Source)] A mapping of file paths to source objects.
 		attr :sources
 		
 		# All definitions which have been parsed.
-		# @attribute [Hash(String, Definition)]
+		# @attribute [Hash(String, Definition)] A mapping of qualified names to definitions.
 		attr :definitions
 		
 		# A (prefix) trie of lexically scoped definitions.
-		# @attribute [Trie]
+		# @attribute [Trie] The trie structure for efficient lookups.
 		attr :trie
 		
 		# Updates the index by parsing the specified files.
 		# All extracted definitions are merged into the existing index.
-		#
-		# @parameter paths [Array(String)] The source file paths.
+		# @parameter paths [Array(String)] The source file paths to parse and index.
 		def update(paths)
 			paths.each do |path|
 				if source = @languages.source_for(path)
+					# Store the source file:
 					@sources[path] = source
 					
+					# Extract and index all definitions:
 					source.definitions do |symbol|
 						# $stderr.puts "Adding #{symbol.qualified_name} to #{symbol.lexical_path.join(' -> ')}"
 						
+						# Add to definitions lookup:
 						@definitions[symbol.qualified_name] = symbol
-						@trie.insert(symbol.path, symbol)
+						
+						# Add to trie for hierarchical lookup:
+						@trie.insert(symbol.full_path, symbol)
 					end
 				end
 			end
 		end
 		
 		# Lookup the specified reference and return matching definitions.
-		#
 		# @parameter reference [Language::Reference] The reference to match.
 		# @parameter relative_to [Definition] Lookup the reference relative to the scope of this definition.
+		# @returns [Definition | Nil] The best matching definition, or nil if not found.
 		def lookup(reference, relative_to: nil)
 			if reference.absolute? || relative_to.nil?
+				# Start from root scope:
 				lexical_path = []
 			else
-				lexical_path = relative_to.path.dup
+				# Start from the given definition's scope:
+				lexical_path = relative_to.full_path.dup
 			end
 			
 			path = reference.path
 			
 			while true
+				# Get the current scope node:
 				node = @trie.lookup(lexical_path)
 				
 				if node.children[path.first]
 					if target = node.lookup(path)
+						# Return the best matching definition:
 						return reference.best(target.values)
 					else
 						return nil
 					end
 				end
 				
+				# Move up one scope level:
 				break if lexical_path.empty?
 				lexical_path.pop
 			end

data/lib/decode/language/generic.rb

@@ -3,53 +3,69 @@
 # Released under the MIT License.
 # Copyright, 2020-2024, by Samuel Williams.
 
-require_relative 'reference'
-require_relative '../documentation'
+require_relative "reference"
+require_relative "../documentation"
 
 module Decode
 	module Language
+		# Represents a generic language implementation that can be extended for specific languages.
 		class Generic
 			EXTENSIONS = []
 			
 			TAGS = Comment::Tags.build do |tags|
-				tags['attribute'] = Comment::Attribute
-				tags['parameter'] = Comment::Parameter
-				tags['option'] = Comment::Option
-				tags['yields'] = Comment::Yields
-				tags['returns'] = Comment::Returns
-				tags['raises'] = Comment::Raises
-				tags['throws'] = Comment::Throws
+				tags["attribute"] = Comment::Attribute
+				tags["parameter"] = Comment::Parameter
+				tags["option"] = Comment::Option
+				tags["yields"] = Comment::Yields
+				tags["returns"] = Comment::Returns
+				tags["raises"] = Comment::Raises
+				tags["throws"] = Comment::Throws
 				
-				tags['deprecated'] = Comment::Pragma
+				tags["deprecated"] = Comment::Pragma
 				
-				tags['asynchronous'] = Comment::Pragma
+				tags["asynchronous"] = Comment::Pragma
 				
-				tags['public'] = Comment::Pragma
-				tags['private'] = Comment::Pragma
+				tags["public"] = Comment::Pragma
+				tags["private"] = Comment::Pragma
 			end
 			
+			# Initialize a new generic language.
+			# @parameter name [String] The name of the language.
+			# @parameter extensions [Array(String)] File extensions for this language.
+			# @parameter tags [Comment::Tags] The comment tags to recognize.
 			def initialize(name, extensions: self.class::EXTENSIONS, tags: self.class::TAGS)
 				@name = name
 				@extensions = extensions
 				@tags = tags
 			end
 			
+			# The name of this language.
+			# @attribute [String] The language name.
 			attr :name
 			
+			# Get all names for this language.
+			# @returns [Array(String)] An array containing the language name.
 			def names
 				[@name]
 			end
 			
+			# The file extensions this language supports.
+			# @attribute [Array(String)] The supported file extensions.
 			attr :extensions
 			
+			# The comment tags this language recognizes.
+			# @attribute [Comment::Tags] The tag definitions.
 			attr :tags
 			
 			# Generate a language-specific reference.
-			# @parameter identifier [String] A valid identifier.
+			# @parameter identifier [String] A valid identifier for this language.
+			# @returns [Reference] A reference object for the given identifier.
 			def reference_for(identifier)
 				Reference.new(identifier, self)
 			end
 			
+			# Get the parser for this language.
+			# @returns [Parser | Nil] The parser instance, or nil if not available.
 			def parser
 				nil
 			end

data/lib/decode/language/reference.rb

@@ -17,20 +17,20 @@ module Decode
 				@path = nil
 			end
 			
+			# Generate a string representation of the reference.
 			def to_s
 				"{#{self.language} #{self.identifier}}"
 			end
 			
+			# Generate a debug representation of the reference.
 			def inspect
 				"\#<#{self.class} {#{self.identifier}}>"
 			end
 			
-			# The identifier part of the reference.
-			# @attribute [String]
+			# @attribute [String] The identifier part of the reference.
 			attr :identifier
 			
-			# The language associated with this reference.
-			# @attribute [Language::Generic]
+			# @attribute [Language::Generic] The language associated with this reference.
 			attr :language
 			
 			# Whether the reference starts at the base of the lexical tree.
@@ -38,20 +38,27 @@ module Decode
 				!self.relative?
 			end
 			
+			# Check if this is a relative reference.
 			def relative?
 				prefix, name = self.lexical_path.first
 				
 				return prefix.nil?
 			end
 			
+			# Split an identifier into prefix and name components.
+			# @parameter identifier [String] The identifier to split.
 			def split(identifier)
 				identifier.scan(/(\W+)?(\w+)/)
 			end
 			
+			# Get the lexical path of this reference.
 			def lexical_path
 				@lexical_path ||= self.split(@identifier)
 			end
 			
+			# Calculate the priority of a definition for matching.
+			# @parameter definition [String] The definition to check.
+			# @parameter prefix [String] The prefix to match against.
 			def priority(definition, prefix)
 				if prefix.nil?
 					return 1
@@ -62,6 +69,8 @@ module Decode
 				end
 			end
 			
+			# Find the best matching definition from a list.
+			# @parameter definitions [Array(String)] The definitions to choose from.
 			def best(definitions)
 				prefix, name = lexical_path.last
 				

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

@@ -0,0 +1,41 @@
+# frozen_string_literal: true
+
+# Released under the MIT License.
+# Copyright, 2020-2024, by Samuel Williams.
+
+require_relative "definition"
+
+module Decode
+	module Language
+		module Ruby
+			# Represents an alias statement, e.g., `alias new_name old_name` or `alias_method :new_name, :old_name`
+			class Alias < Definition
+				# Initialize a new alias definition.
+				# @parameter new_name [String] The new name for the alias.
+				# @parameter old_name [String] The original name being aliased.
+				# @parameter options [Hash] Additional options for the definition.
+				def initialize(new_name, old_name, **options)
+					super(new_name, **options)
+					@old_name = old_name
+				end
+				
+				attr :old_name
+				
+				# Generate a short form representation of the alias.
+				def short_form
+					"alias #{self.name} #{@old_name}"
+				end
+				
+				# Generate a long form representation of the alias.
+				def long_form
+					"alias #{self.name} #{@old_name}"
+				end
+				
+				# Generate a string representation of the alias.
+				def to_s
+					"#{self.class.name} #{self.name} -> #{@old_name}"
+				end
+			end
+		end
+	end
+end

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

@@ -3,7 +3,7 @@
 # Released under the MIT License.
 # Copyright, 2020-2024, by Samuel Williams.
 
-require_relative 'definition'
+require_relative "definition"
 
 module Decode
 	module Language
@@ -13,17 +13,18 @@ module Decode
 				# The short form of the attribute.
 				# e.g. `attr :value`.
 				def short_form
-					case @node.type
-					when :block
+					case @node&.type
+					when :block_node
 						"#{@name} { ... }"
 					else
-						@node.location.expression.source
+						@node&.location&.slice || @name
 					end
 				end
 				
+				# Generate a long form representation of the attribute.
 				def long_form
-					if @node.location.line == @node.location.last_line
-						@node.location.expression.source
+					if @node&.location&.start_line == @node&.location&.end_line
+						@node.location.slice
 					else
 						short_form
 					end

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

@@ -3,7 +3,7 @@
 # Released under the MIT License.
 # Copyright, 2020-2024, by Samuel Williams.
 
-require_relative 'definition'
+require_relative "definition"
 
 module Decode
 	module Language
@@ -15,6 +15,7 @@ module Decode
 					true
 				end
 				
+				# Generate a nested name for the block.
 				def nested_name
 					".#{name}"
 				end
@@ -41,6 +42,8 @@ module Decode
 					self.qualified_name
 				end
 				
+				# Convert the block to a different kind of definition.
+				# @parameter kind [Symbol] The kind to convert to.
 				def convert(kind)
 					case kind
 					when :attribute

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

@@ -3,7 +3,7 @@
 # Released under the MIT License.
 # Copyright, 2020-2024, by Samuel Williams.
 
-require_relative 'definition'
+require_relative "definition"
 
 module Decode
 	module Language
@@ -12,22 +12,32 @@ module Decode
 			class Call < Definition
 				# A block can sometimes be a container for other definitions.
 				def container?
-					false
+					@node&.block && @node.block.opening == "do"
 				end
 				
 				# The short form of the class.
 				# e.g. `foo`.
 				def short_form
-					@name.to_s
+					if @node&.block && @node.block.opening == "{"
+						"#{name} { ... }"
+					else
+						name.to_s
+					end
 				end
 				
 				# The long form of the class.
 				# e.g. `foo(:bar)`.
 				def long_form
-					if @node.location.line == @node.location.last_line
-						@node.location.expression.source
+					if @node.location.start_line == @node.location.end_line
+						@node.location.slice
 					else
-						self.short_form
+						# For multiline calls, use the actual call name with arguments
+						if @node.arguments && @node.arguments.arguments.any?
+							arg_text = @node.arguments.arguments.map { |arg| arg.location.slice }.join(", ")
+							"#{@node.name}(#{arg_text})"
+						else
+							@node.name.to_s
+						end
 					end
 				end