decode 0.24.2 → 0.24.4

data/lib/decode/definition.rb

@@ -10,10 +10,11 @@ module Decode
 	class Definition
 		# Initialize the symbol.
 		# @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.
-		# @parameter source [Source] The source file containing this definition.
+		# @parameter parent [Definition?] The parent lexical scope.
+		# @parameter language [Language::Generic?] The language in which the symbol is defined in.
+		# @parameter comments [Array(String)?] The comments associated with the definition.
+		# @parameter visibility [Symbol] The visibility of the definition.
+		# @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)
 			
@@ -23,6 +24,7 @@ module Decode
 			
 			@comments = comments
 			@visibility = visibility
+			@documentation = nil
 			
 			@full_path = nil
 			@qualified_name = nil
@@ -37,9 +39,7 @@ module Decode
 		# Generate a string representation of the definition.
 		alias to_s inspect
 		
-		# The symbol name.
-		# e.g. `:Decode`.
-		# @attribute [Symbol]
+		# @attribute [Symbol] The symbol name e.g. `:Decode`.
 		def name
 			@path.last
 		end
@@ -48,10 +48,11 @@ module Decode
 		attr :path
 		
 		# The full path to the definition.
+		# @returns [Array(Symbol)] The complete path from root to this definition.
 		def full_path
 			@full_path ||= begin
-				if @parent
-					@parent.full_path + @path
+				if parent = @parent
+					parent.full_path + @path
 				else
 					@path
 				end
@@ -62,56 +63,57 @@ module Decode
 		# @returns [Array(Symbol)] The complete path from root to this definition.
 		alias lexical_path full_path
 		
-		# @attribute [Definition | Nil] The parent definition, defining lexical scope.
+		# @attribute [Definition?] The parent definition, defining lexical scope.
 		attr :parent
 		
 		# @attribute [Language::Generic] The language the symbol is defined within.
 		attr :language
 		
-		# @attribute [Source | Nil] The source file containing this definition.
+		# @attribute [Source?] The source file containing this definition.
 		attr :source
 		
-		# @attribute [Array(String)] The comment lines which directly preceeded the definition.
+		# @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] True if the definition is public.
+		# @returns [bool] 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.
+		# @returns [bool] True if the definition has non-empty comments.
 		def documented?
-			@comments&.any?
+			@comments&.any? || false
 		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].join("::")
+				if parent = @parent
+					[parent.qualified_name, self.nested_name].join("::")
 				else
 					self.nested_name
 				end
 			end
 		end
 		
-		# The name relative to the parent.
-		# @returns [String]
+		# @returns [String] The name relative to the parent.
 		def nested_name
 			@nested_name ||= "#{@path.join("::")}"
 		end
 		
 		# Does the definition name match the specified prefix?
-		# @returns [Boolean]
+		# @parameter prefix [String] The prefix to match against.
+		# @returns [bool]
 		def start_with?(prefix)
 			self.nested_name.start_with?(prefix)
 		end
 		
 		# Convert this definition into another kind of definition.
+		# @parameter kind [Symbol] The kind to convert to.
 		def convert(kind)
 			raise ArgumentError, "Unable to convert #{self} into #{kind}!"
 		end
@@ -119,14 +121,14 @@ module Decode
 		# A short form of the definition.
 		# e.g. `def short_form`.
 		#
-		# @returns [String | Nil]
+		# @returns [String?]
 		def short_form
 		end
 		
 		# A long form of the definition.
 		# e.g. `def initialize(kind, name, comments, **options)`.
 		#
-		# @returns [String | Nil]
+		# @returns [String?]
 		def long_form
 			self.short_form
 		end
@@ -134,50 +136,50 @@ module Decode
 		# A long form which uses the qualified name if possible.
 		# Defaults to {long_form}.
 		#
-		# @returns [String | Nil]
+		# @returns [String?]
 		def qualified_form
 			self.long_form
 		end
 		
 		# Whether the definition spans multiple lines.
 		#
-		# @returns [Boolean]
+		# @returns [bool]
 		def multiline?
 			false
 		end
 		
 		# The full text of the definition.
 		#
-		# @returns [String | Nil]
+		# @returns [String?]
 		def text
 		end
 		
 		# Whether this definition can contain nested definitions.
 		#
-		# @returns [Boolean]
+		# @returns [bool]
 		def container?
 			false
 		end
 		
 		# Whether this represents a single entity to be documented (along with it's contents).
 		#
-		# @returns [Boolean]
+		# @returns [bool]
 		def nested?
 			container?
 		end
 		
 		# Structured access to the definitions comments.
 		#
-		# @returns [Documentation | Nil] A {Documentation} instance if this definition has comments.
+		# @returns [Documentation?] A {Documentation} instance if this definition has comments.
 		def documentation
-			if @comments&.any?
-				@documentation ||= Documentation.new(@comments, @language)
+			if comments = @comments and comments.any?
+				@documentation ||= Documentation.new(comments, @language)
 			end
 		end
 		
 		# The location of the definition.
 		#
-		# @returns [Location | Nil] A {Location} instance if this definition has a location.
+		# @returns [Location?] A {Location} instance if this definition has a location.
 		def location
 			nil
 		end

data/lib/decode/documentation.rb

@@ -7,6 +7,7 @@ require_relative "comment/node"
 
 require_relative "comment/tags"
 require_relative "comment/attribute"
+require_relative "comment/constant"
 require_relative "comment/parameter"
 require_relative "comment/option"
 require_relative "comment/pragma"
@@ -21,20 +22,24 @@ module Decode
 		# Initialize the documentation with an array of comments, within a specific language.
 		#
 		# @parameter comments [Array(String)] An array of comment lines.
-		# @parameter language [Language] The language in which the comments were extracted.
-		def initialize(comments, language = nil)
+		# @parameter language [Language::Generic?] The language in which the comments were extracted.
+		def initialize(comments, language)
+			super(nil)
+			
 			@comments = comments
 			@language = language
 			
-			language.tags.parse(@comments.dup) do |node|
-				self.add(node)
+			if language
+				language.tags.parse(@comments.dup) do |node|
+					self.add(node)
+				end
 			end
 		end
 		
 		# @attribute [Array(String)] The underlying comments from which the documentation is extracted.
 		attr :comments
 		
-		# @attribute [Language::Generic] The language in which the documentation was extracted from.
+		# @attribute [Language::Generic?] The language in which the documentation was extracted from.
 		attr :language
 	end
 end

data/lib/decode/index.rb

@@ -11,10 +11,11 @@ require_relative "languages"
 module Decode
 	# Represents a list of definitions organised for quick lookup and lexical enumeration.
 	class Index
-		# Create and populate an index from the given paths.
-		# @parameter paths [Array(String)] The paths to index (files, directories, or glob patterns).
+		# Create and populate an index from the given paths.  
+		# @parameter paths [Array(String)] Variable number of paths to index (files, directories, or glob patterns).
 		# @parameter languages [Languages] The languages to support in this index.
 		# @returns [Index] A new index populated with definitions from the given paths.
+		# @rbs (*String, ?languages: Languages) -> Index
 		def self.for(*paths, languages: Languages.all)
 			# Resolve all paths to actual files:
 			resolved_paths = paths.flat_map do |path|
@@ -74,7 +75,7 @@ module Decode
 		attr :definitions
 		
 		# A (prefix) trie of lexically scoped definitions.
-		# @attribute [Trie] The trie structure for efficient lookups.
+		# @attribute [Trie[Definition]] The trie structure for efficient lookups.
 		attr :trie
 		
 		# Updates the index by parsing the specified files.
@@ -102,12 +103,12 @@ module Decode
 		
 		# 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.
+		# @parameter relative_to [Definition?] Lookup the reference relative to the scope of this definition.
+		# @returns [Definition?] 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 = []
+				lexical_path = [] #: Array[Symbol]
 			else
 				# Start from the given definition's scope:
 				lexical_path = relative_to.full_path.dup
@@ -122,7 +123,11 @@ module Decode
 				if node.children[path.first]
 					if target = node.lookup(path)
 						# Return the best matching definition:
-						return reference.best(target.values)
+						if values = target.values
+							return reference.best(values)
+						else
+							return nil
+						end
 					else
 						return nil
 					end

data/lib/decode/language/generic.rb

@@ -65,7 +65,7 @@ module Decode
 			end
 			
 			# Get the parser for this language.
-			# @returns [Parser | Nil] The parser instance, or nil if not available.
+			# @returns [untyped] The parser instance, or nil if not available.
 			def parser
 				nil
 			end
@@ -92,6 +92,15 @@ module Decode
 					parser.segments_for(source, &block)
 				end
 			end
+			
+			# Generate a code representation with syntax highlighting and link resolution.
+			# @parameter text [String] The source code text to format.
+			# @parameter index [Index] The index for resolving references.
+			# @parameter relative_to [Definition] The definition to resolve relative references from.
+			# @returns [untyped] A formatted code object with syntax highlighting.
+			def code_for(text, index, relative_to: nil)
+				raise NotImplementedError, "Code generation is not implemented for #{self.class}!"
+			end
 		end
 	end
 end

data/lib/decode/language/reference.rb

@@ -9,6 +9,8 @@ module Decode
 		class Reference
 			# Initialize the reference.
 			# @parameter identifier [String] The identifier part of the reference.
+			# @parameter language [Language::Generic] The language this reference belongs to.
+			# @parameter lexical_path [Array(String)?] The lexical path scope for resolution.
 			def initialize(identifier, language, lexical_path = nil)
 				@identifier = identifier
 				@language = language
@@ -70,12 +72,13 @@ module Decode
 			end
 			
 			# Find the best matching definition from a list.
-			# @parameter definitions [Array(String)] The definitions to choose from.
+			# @parameter definitions [Array(Definition)] The definitions to choose from.
+			# @returns [Definition?] The best matching definition, if any.
 			def best(definitions)
 				prefix, name = lexical_path.last
 				
-				first = nil
-				without_prefix = nil
+				first = nil #: Definition?
+				without_prefix = nil #: Definition?
 				
 				definitions.each do |definition|
 					first ||= definition
@@ -93,7 +96,7 @@ module Decode
 			end
 			
 			# The lexical path of the reference.
-			# @returns [Array(String)]
+			# @returns [Array(Symbol)]
 			def path
 				@path ||= self.lexical_path.map{|_, name| name.to_sym}
 			end

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

@@ -58,13 +58,13 @@ module Decode
 				end
 				
 				# A singleton class is a container for other definitions.
-				# @returns [Boolean]
+				# @returns [bool]
 				def container?
 					true
 				end
 				
 				# Typically, a singleton class does not contain other definitions.
-				# @returns [Boolean]
+				# @returns [bool]
 				def nested?
 					false
 				end

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

@@ -16,9 +16,9 @@ module Decode
 				# Initialize a new code block.
 				# @parameter text [String] The code text.
 				# @parameter index [Index] The index to use.
-				# @parameter relative_to [Definition] The definition this code is relative to.
-				# @parameter language [Language] The language of the code.
-				def initialize(text, index, relative_to: nil, language: relative_to&.language)
+				# @parameter relative_to [Definition?] The definition this code is relative to.
+				# @parameter language [Language::Generic] The language of the code.
+				def initialize(text, index, relative_to: nil, language:)
 					@text = text
 					@root = ::Prism.parse(text)
 					@index = index
@@ -26,12 +26,24 @@ module Decode
 					@language = language
 				end
 				
+				# @attribute [String] The code text.
 				attr :text
 				
+				# @attribute [untyped] The parsed syntax tree.
+				attr :root
+				
+				# @attribute [Index] The index to use for lookups.
+				attr :index
+				
+				# @attribute [Definition?] The definition this code is relative to.
+				attr :relative_to
+				
+				# @attribute [Language::Generic] The language of the code.
 				attr :language
 				
 				# Extract definitions from the code.
 				# @parameter into [Array] The array to extract definitions into.
+				# @returns [Array] The array with extracted definitions.
 				def extract(into = [])
 					if @index
 						traverse(@root.value, into)
@@ -42,6 +54,10 @@ module Decode
 				
 				private
 				
+				# Traverse the syntax tree and extract definitions.
+				# @parameter node [untyped] The syntax tree node to traverse.
+				# @parameter into [Array] The array to extract definitions into.
+				# @returns [self]
 				def traverse(node, into)
 					case node&.type
 					when :program_node
@@ -75,6 +91,8 @@ module Decode
 							traverse(child, into)
 						end
 					end
+					
+					return self
 				end
 			end
 		end

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

@@ -31,13 +31,25 @@ module Decode
 				attr_accessor :visibility
 				
 				# Check if this definition is public.
-				# @returns [Boolean] True if the definition is public.
+				# @returns [bool] True if the definition is public.
 				def public?
 					@visibility == :public
 				end
 				
+				# Check if this definition is protected.
+				# @returns [bool] True if the definition is protected.
+				def protected?
+					@visibility == :protected
+				end
+				
+				# Check if this definition is private.
+				# @returns [bool] True if the definition is private.
+				def private?
+					@visibility == :private
+				end
+				
 				# Check if this definition spans multiple lines.
-				# @returns [Boolean] True if the definition spans multiple lines.
+				# @returns [bool] True if the definition spans multiple lines.
 				def multiline?
 					@node.location.start_line != @node.location.end_line
 				end
@@ -63,7 +75,7 @@ module Decode
 				end
 				
 				# Get the location of this definition.
-				# @returns [Location | Nil] The location object if source is available.
+				# @returns [Location?] The location object if source is available.
 				def location
 					if @source and location = @node&.location
 						Location.new(@source.path, location.start_line)

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

@@ -19,6 +19,7 @@ module Decode
 				
 				TAGS = Comment::Tags.build do |tags|
 					tags["attribute"] = Comment::Attribute
+					tags["constant"] = Comment::Constant
 					tags["parameter"] = Comment::Parameter
 					tags["option"] = Comment::Option
 					tags["yields"] = Comment::Yields
@@ -37,7 +38,7 @@ module Decode
 				end
 				
 				# Get the parser for Ruby source code.
-				# @returns [Parser] The Ruby parser instance.
+				# @returns [Language::Ruby::Parser] The Ruby parser instance.
 				def parser
 					@parser ||= Parser.new(self)
 				end