decode 0.13.0 → 0.14.0

data/lib/decode/comment/text.rb

@@ -0,0 +1,37 @@
+# Copyright, 2020, by Samuel G. D. Williams. <http://www.codeotaku.com>
+# 
+# Permission is hereby granted, free of charge, to any person obtaining a copy
+# of this software and associated documentation files (the "Software"), to deal
+# in the Software without restriction, including without limitation the rights
+# to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+# copies of the Software, and to permit persons to whom the Software is
+# furnished to do so, subject to the following conditions:
+# 
+# The above copyright notice and this permission notice shall be included in
+# all copies or substantial portions of the Software.
+# 
+# THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+# IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+# FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+# AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+# LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+# OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
+# THE SOFTWARE.
+
+require_relative 'node'
+
+module Decode
+	module Comment
+		# A structured comment.
+		class Text
+			def initialize(line)
+				@line = line
+			end
+			
+			attr :line
+			
+			def traverse
+			end
+		end
+	end
+end

data/lib/decode/comment/throws.rb

@@ -0,0 +1,32 @@
+# Copyright, 2020, by Samuel G. D. Williams. <http://www.codeotaku.com>
+# 
+# Permission is hereby granted, free of charge, to any person obtaining a copy
+# of this software and associated documentation files (the "Software"), to deal
+# in the Software without restriction, including without limitation the rights
+# to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+# copies of the Software, and to permit persons to whom the Software is
+# furnished to do so, subject to the following conditions:
+# 
+# The above copyright notice and this permission notice shall be included in
+# all copies or substantial portions of the Software.
+# 
+# THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+# IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+# FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+# AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+# LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+# OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
+# THE SOFTWARE.
+
+require_relative 'attribute'
+
+module Decode
+	module Comment
+		# Identifies that a method might throw a specific symbol.
+		#
+		# - `@throws [:skip] To skip recursion.`
+		#
+		class Throws < Attribute
+		end
+	end
+end

data/lib/decode/comment/yields.rb

@@ -0,0 +1,52 @@
+# Copyright, 2020, by Samuel G. D. Williams. <http://www.codeotaku.com>
+# 
+# Permission is hereby granted, free of charge, to any person obtaining a copy
+# of this software and associated documentation files (the "Software"), to deal
+# in the Software without restriction, including without limitation the rights
+# to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+# copies of the Software, and to permit persons to whom the Software is
+# furnished to do so, subject to the following conditions:
+# 
+# The above copyright notice and this permission notice shall be included in
+# all copies or substantial portions of the Software.
+# 
+# THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+# IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+# FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+# AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+# LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+# OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
+# THE SOFTWARE.
+
+require_relative 'tag'
+
+module Decode
+	module Comment
+		# Describes a block parameter.
+		#
+		# - `@yields {|person| ... } If a block is given.`
+		#
+		# Should contain nested parameters.
+		class Yields < Tag
+			PATTERN = /\A(?<block>{.*?})(\s+(?<details>.*?))?\Z/
+			
+			def self.build(directive, match)
+				node = self.new(directive, match[:block])
+				
+				if details = match[:details]
+					node.add(Text.new(details))
+				end
+				
+				return node
+			end
+			
+			def initialize(directive, block)
+				super(directive)
+				
+				@block = block
+			end
+			
+			attr :block
+		end
+	end
+end

data/lib/decode/definition.rb

@@ -22,10 +22,10 @@ module Decode
 	# A symbol with attached documentation.
 	class Definition
 		# Initialize the symbol.
-		# @param name [Symbol] The name of the definition.
-		# @param parent [Symbol] The parent lexical scope.
-		# @param language [Language] The language in which the symbol is defined in.
-		# @param comments [Array(String)] The comments associated with the definition.
+		# @parameter name [Symbol] The name of the definition.
+		# @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
 			
@@ -53,11 +53,11 @@ module Decode
 		attr :language
 		
 		# The comment lines which directly preceeded the definition.
-		# @attr [Array(String)]
+		# @attribute [Array(String)]
 		attr :comments
 		
 		# The qualified name is an absolute name which includes any and all namespacing.
-		# @return [String]
+		# @returns [String]
 		def qualified_name
 			@qualified_name ||= begin
 				if @parent
@@ -69,7 +69,7 @@ module Decode
 		end
 		
 		# The name of this definition plus the nesting prefix.
-		# @return [String]
+		# @returns [String]
 		def nested_name
 			"::#{@name}"
 		end
@@ -78,12 +78,13 @@ module Decode
 			self.nested_name.start_with?(prefix)
 		end
 		
+		# Convert this definition into another kind of definition.
 		def convert(kind)
 			raise ArgumentError, "Unable to convert #{self} into #{kind}!"
 		end
 		
 		# The lexical scope which is an array of lexical {Key} instances as generated by {key}.
-		# @return [Array]
+		# @returns [Array]
 		def path
 			if @path
 				# Cached version:
@@ -102,14 +103,14 @@ module Decode
 		# A short form of the definition.
 		# e.g. `def short_form`.
 		#
-		# @return [String | nil]
+		# @returns [String | nil]
 		def short_form
 		end
 		
 		# A long form of the definition.
 		# e.g. `def initialize(kind, name, comments, **options)`.
 		#
-		# @return [String | nil]
+		# @returns [String | nil]
 		def long_form
 			self.short_form
 		end
@@ -117,44 +118,44 @@ module Decode
 		# A long form which uses the qualified name if possible.
 		# Defaults to {long_form}.
 		#
-		# @return  [String | nil]
+		# @returns [String | nil]
 		def qualified_form
 			self.long_form
 		end
 		
 		# Whether the definition spans multiple lines.
 		#
-		# @return [Boolean]
+		# @returns [Boolean]
 		def multiline?
 			false
 		end
 		
 		# The full text of the definition.
 		#
-		# @return [String | nil]
+		# @returns [String | nil]
 		def text
 		end
 		
 		# Whether this definition can contain nested definitions.
 		#
-		# @return [Boolean]
+		# @returns [Boolean]
 		def container?
 			false
 		end
 		
 		# Whether this represents a single entity to be documented (along with it's contents).
 		#
-		# @return [Boolean]
+		# @returns [Boolean]
 		def nested?
 			container?
 		end
 		
 		# Structured access to the definitions comments.
 		#
-		# @return [Documentation | Nil] A `Documentation` if this definition has comments.
+		# @returns [Documentation | Nil] A {Documentation} instance if this definition has comments.
 		def documentation
 			if @comments&.any?
-				@documentation ||= Documentation.new(@comments)
+				@documentation ||= Documentation.new(@comments, @language)
 			end
 		end
 	end

data/lib/decode/documentation.rb

@@ -18,83 +18,38 @@
 # OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
 # THE SOFTWARE.
 
+require_relative 'comment/node'
+
+require_relative 'comment/attribute'
+require_relative 'comment/parameter'
+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.
-	class Documentation
+	class Documentation < Comment::Node
 		# Initialize the documentation with an array of comments, within a specific language.
 		#
-		# @param comments [Array(String)] An array of comment lines.
-		# @param language [Language] The language in which the comments were extracted.
+		# @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)
 			@comments = comments
 			@language = language
-		end
-		
-		# The language in which the documentation was extracted from.
-		attr :language
-		
-		DESCRIPTION = /\A\s*([^@\s].*)?\z/
-		
-		# The text-only lines of the comment block.
-		#
-		# @yield [String]
-		# @return [Enumerable]
-		def description
-			return to_enum(:description) unless block_given?
-			
-			# We track empty lines and only yield a single empty line when there is another line of text:
-			gap = false
-			
-			@comments.each do |comment|
-				if match = comment.match(DESCRIPTION)
-					if match[1]
-						if gap
-							yield ""
-							gap = false
-						end
-						
-						yield match[1]
-					else
-						gap = true
-					end
-				else
-					break
-				end
-			end
-		end
-		
-		ATTRIBUTE = /\A\s*@(?<name>.*?)\s+(?<value>.*?)\z/
-		
-		# The attribute lines of the comment block.
-		# e.g. `@return [String]`.
-		#
-		# @yield [String]
-		# @return [Enumerable]
-		def attributes
-			return to_enum(:attributes) unless block_given?
 			
-			@comments.each do |comment|
-				if match = comment.match(ATTRIBUTE)
-					yield match
-				end
+			language.tags.parse(@comments.dup) do |node|
+				self.add(node)
 			end
 		end
 		
-		PARAMETER = /\A\s*@param\s+(?<name>.*?)\s+\[(?<type>.*?)\]\s+(?<details>.*?)\z/
+		# The underlying comments from which the documentation is extracted.
+		# @attribute [Array(String)]
+		attr :comments
 		
-		# The parameter lines of the comment block.
-		# e.g. `@param value [String] The value.`
-		#
-		# @yield [String]
-		# @return [Enumerable]
-		def parameters
-			return to_enum(:parameters) unless block_given?
-			
-			@comments.each do |comment|
-				if match = comment.match(PARAMETER)
-					yield match
-				end
-			end
-		end
+		# The language in which the documentation was extracted from.
+		# @attribute [Language]
+		attr :language
 	end
 end

data/lib/decode/index.rb

@@ -38,26 +38,26 @@ module Decode
 		end
 		
 		# All supported languages for this index.
-		# @attr [Languages]
+		# @attribute [Languages]
 		attr :languages
 		
 		# All source files that have been parsed.
-		# @attr [Array(Source)]
+		# @attribute [Array(Source)]
 		attr :sources
 		
 		# All definitions which have been parsed.
-		# @attr [Array(Symbol)]
+		# @attribute [Array(Symbol)]
 		attr :definitions
 		
 		# A (prefix) trie of lexically scoped definitions.
-		# @attr [Trie]
+		# @attribute [Trie]
 		
 		attr :trie
 		
 		# Updates the index by parsing the specified files.
 		# All extracted definitions are merged into the existing index.
 		#
-		# @param paths [Array(String)] The source file paths.
+		# @parameter paths [Array(String)] The source file paths.
 		def update(paths)
 			paths.each do |path|
 				if source = @languages.source_for(path)
@@ -75,8 +75,8 @@ module Decode
 		
 		# Lookup the specified reference and return matching definitions.
 		#
-		# @param reference [Reference] The reference to match.
-		# @param relative_to [Definition] Lookup the reference relative to the scope of this definition.
+		# @parameter reference [Language::Reference] The reference to match.
+		# @parameter relative_to [Definition] Lookup the reference relative to the scope of this definition.
 		def lookup(reference, relative_to: nil)
 			if reference.absolute? || relative_to.nil?
 				lexical_path = []

data/lib/decode/language/generic.rb

@@ -36,13 +36,13 @@ module Decode
 			end
 			
 			# Parse the input yielding definitions.
-			# @block `{|definition| ...}`
+			# @block {|definition| ... }
 			# @yield definition [Definition]
 			def definitions_for(input, &block)
 			end
 			
 			# Parse the input yielding interleaved comments and code segments.
-			# @block `{|segment| ...}`
+			# @block {|segment| ... }
 			# @yield segment [Segment]
 			def segments_for(input, &block)
 			end

data/lib/decode/language/reference.rb

@@ -23,7 +23,7 @@ module Decode
 		# An reference which can be resolved to zero or more definitions.
 		class Reference
 			# Initialize the reference.
-			# @param identifier [String] The identifier part of the reference.
+			# @parameter identifier [String] The identifier part of the reference.
 			def initialize(identifier, language)
 				@identifier = identifier
 				@language = language
@@ -32,8 +32,16 @@ module Decode
 				@path = nil
 			end
 			
+			def to_s
+				"{#{self.language} #{self.identifier}}"
+			end
+			
+			def inspect
+				"\#<#{self.class} {#{self.identifier}}>"
+			end
+			
 			# The identifier part of the reference.
-			# @attr [String]
+			# @attribute [String]
 			attr :identifier
 			
 			# The language associated with this reference.
@@ -69,7 +77,7 @@ module Decode
 			end
 			
 			# The lexical path of the reference.
-			# @return [Array(String)]
+			# @returns [Array(String)]
 			def path
 				@path ||= self.lexical_path.map{|_, name| name.to_sym}
 			end

data/lib/decode/language/ruby.rb

@@ -21,9 +21,14 @@
 require_relative 'ruby/reference'
 require_relative 'ruby/parser'
 
+require_relative '../comment/tags'
+require_relative '../comment/parameter'
+require_relative '../comment/yields'
+require_relative '../comment/returns'
+
 module Decode
 	module Language
-		# The Ruby language.
+		# An interface for extracting information from Ruby source code.
 		module Ruby
 			# The canoical name of the language for use in output formatting.
 			# e.g. source code highlighting.
@@ -39,21 +44,45 @@ module Decode
 				['.rb', '.ru']
 			end
 			
+			TAGS = Comment::Tags.build do |tags|
+				tags['attribute'] = Comment::Attribute
+				tags['parameter'] = Comment::Parameter
+				tags['yields'] = Comment::Yields
+				tags['returns'] = Comment::Returns
+				tags['raises'] = Comment::Raises
+				tags['throws'] = Comment::Throws
+				
+				tags['reentrant'] = Comment::Pragma
+				tags['deprecated'] = Comment::Pragma
+				tags['blocking'] = Comment::Pragma
+				tags['asynchronous'] = Comment::Pragma
+			end
+			
+			def self.tags
+				TAGS
+			end
+			
 			# Generate a language-specific reference.
+			# @parameter identifier [String] A valid identifier.
 			def self.reference_for(identifier)
 				Reference.new(identifier, self)
 			end
 			
 			# Parse the input yielding definitions.
-			# @block `{|definition| ...}`
-			# @yield definition [Definition]
+			# @parameter input [File] The input file which contains the source code.
+			# @yields {|definition| ...} Receives the definitions extracted from the source code.
+			# 	@parameter definition [Definition] The source code definition including methods, classes, etc.
+			# @returns [Enumerator(Segment)] If no block given.
 			def self.definitions_for(input, &block)
 				Parser.new.definitions_for(input, &block)
 			end
 			
-			# Parse the input yielding interleaved comments and code segments.
-			# @block `{|segment| ...}`
-			# @yield segment [Segment]
+			# Parse the input yielding segments.
+			# Segments are constructed from a block of top level comments followed by a block of code.
+			# @parameter input [File] The input file which contains the source code.
+			# @yields {|segment| ...}
+			# 	@parameter segment [Segment]
+			# @returns [Enumerator(Segment)] If no block given.
 			def self.segments_for(input, &block)
 				Parser.new.segments_for(input, &block)
 			end