decode 0.13.0 → 0.14.0

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

@@ -62,13 +62,13 @@ module Decode
 			# A Ruby-specific singleton class.
 			class Singleton < Definition
 				# A singleton class is a container for other definitions.
-				# @return [Boolean]
+				# @returns [Boolean]
 				def container?
 					true
 				end
 				
 				# Typically, a singleton class does not contain other definitions.
-				# @return [Boolean]
+				# @returns [Boolean]
 				def nested?
 					false
 				end

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

@@ -44,7 +44,7 @@ module Decode
 				end
 				
 				# The source code associated with the definition.
-				# @return [String]
+				# @returns [String]
 				def text
 					expression = @node.location.expression
 					lines = expression.source.lines

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

@@ -207,7 +207,7 @@ module Decode
 				end
 				
 				KIND_ATTRIBUTE = /\A
-					(@(?<kind>attr)\s+(?<value>.*?))|
+					(@(?<kind>attribute)\s+(?<value>.*?))|
 					(@define\s+(?<kind>)\s+(?<value>.*?))
 				\Z/x
 				
@@ -279,6 +279,14 @@ module Decode
 						end
 						
 						yield segment if segment
+					else
+						# One top level segment:
+						segment = Segment.new(
+							extract_comments_for(node, comments),
+							Ruby,	node
+						)
+						
+						yield segment
 					end
 				end
 			end

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

@@ -40,7 +40,7 @@ module Decode
 				end
 				
 				# The source code trailing the comments.
-				# @return [String | nil]
+				# @returns [String | nil]
 				def code
 					@expression.source
 				end

data/lib/decode/segment.rb

@@ -35,15 +35,15 @@ module Decode
 		end
 		
 		# The preceeding comments.
-		# @attr [Array(String)]
+		# @attribute [Array(String)]
 		attr :comments
 		
 		# The language of the code attached to this segment.
-		# @attr [Language]
+		# @attribute [Language]
 		attr :language
 		
 		# An interface for accsssing the documentation of the definition.
-		# @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, @language)
@@ -51,7 +51,7 @@ module Decode
 		end
 		
 		# The source code trailing the comments.
-		# @return [String | nil]
+		# @returns [String | nil]
 		def code
 		end
 	end

data/lib/decode/trie.rb

@@ -31,17 +31,17 @@ module Decode
 			end
 			
 			# A mutable array of all values that terminate at this node.
-			# @attr [Array]
+			# @attribute [Array]
 			attr_accessor :values
 			
 			# A hash table of all children nodes, indexed by name.
-			# @attr [Hash(String, Node)]
+			# @attribute [Hash(String, Node)]
 			attr :children
 			
 			# Look up a lexical path starting at this node.
 			#
-			# @param path [Array(String)] The path to resolve.
-			# @return [Node | Nil]
+			# @parameter path [Array(String)] The path to resolve.
+			# @returns [Node | Nil]
 			def lookup(path, index = 0)
 				if index < path.size
 					if child = @children[path[index]]
@@ -55,9 +55,9 @@ module Decode
 			# Traverse the trie from this node.
 			# Invoke `descend.call` to traverse the children of the current node.
 			#
-			# @param path [Array(String)] The current lexical path.
+			# @parameter path [Array(String)] The current lexical path.
 			#
-			# @block `{|path, node, descend| descend.call}`
+			# @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.
@@ -76,12 +76,12 @@ module Decode
 		end
 		
 		# The root of the trie.
-		# @attr [Node]
+		# @attribute [Node]
 		attr :root
 		
 		# Insert the specified value at the given path into the trie.
-		# @param path [Array(String)] The lexical path where the value will be inserted.
-		# @param value [Object] The value to insert.
+		# @parameter path [Array(String)] The lexical path where the value will be inserted.
+		# @parameter value [Object] The value to insert.
 		def insert(path, value)
 			node = @root
 			
@@ -94,15 +94,15 @@ module Decode
 		
 		# Lookup the values at the specified path.
 		#
-		# @param path [Array(String)] The lexical path which contains the values.
-		# @return [Array(Object) | Nil] The values that existed (or not) 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.
 		def lookup(path)
 			@root.lookup(path)
 		end
 		
 		# Enumerate all lexical scopes under the specified path.
 		#
-		# @block `{|path, values| ...}`
+		# @block {|path, values| ...}
 		# @yield path [Array(String)] The lexical path.
 		# @yield values [Array(Object)] The values that exist at the given path.
 		def each(path = [], &block)

data/lib/decode/version.rb

@@ -19,5 +19,5 @@
 # THE SOFTWARE.
 
 module Decode
-	VERSION = "0.13.0"
+	VERSION = "0.14.0"
 end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: decode
 version: !ruby/object:Gem::Version
-  version: 0.13.0
+  version: 0.14.0
 platform: ruby
 authors:
 - Samuel Williams
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2020-05-08 00:00:00.000000000 Z
+date: 2020-05-10 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: parser
@@ -115,15 +115,19 @@ executables: []
 extensions: []
 extra_rdoc_files: []
 files:
-- ".github/workflows/development.yml"
-- ".gitignore"
-- ".rspec"
-- README.md
 - bake/decode/index.rb
-- decode.gemspec
-- gems.rb
-- guides/extract-symbols/extract.rb
 - lib/decode.rb
+- lib/decode/comment/attribute.rb
+- lib/decode/comment/node.rb
+- lib/decode/comment/parameter.rb
+- lib/decode/comment/pragma.rb
+- lib/decode/comment/raises.rb
+- lib/decode/comment/returns.rb
+- lib/decode/comment/tag.rb
+- lib/decode/comment/tags.rb
+- lib/decode/comment/text.rb
+- lib/decode/comment/throws.rb
+- lib/decode/comment/yields.rb
 - lib/decode/definition.rb
 - lib/decode/documentation.rb
 - lib/decode/index.rb
@@ -159,9 +163,9 @@ require_paths:
 - lib
 required_ruby_version: !ruby/object:Gem::Requirement
   requirements:
-  - - ">="
+  - - "~>"
     - !ruby/object:Gem::Version
-      version: 2.3.0
+      version: '2.5'
 required_rubygems_version: !ruby/object:Gem::Requirement
   requirements:
   - - ">="

data/.github/workflows/development.yml

@@ -1,50 +0,0 @@
-name: Development
-
-on: [push, pull_request]
-
-jobs:
-  test:
-    runs-on: ${{matrix.os}}-latest
-    continue-on-error: ${{matrix.experimental}}
-    
-    strategy:
-      matrix:
-        os:
-          - ubuntu
-        
-        ruby:
-          - 2.5
-          - 2.6
-          - 2.7
-        
-        experimental: [false]
-        env: [""]
-        
-        include:
-          - os: ubuntu
-            ruby: truffleruby
-            experimental: true
-          - os: ubuntu
-            ruby: jruby
-            experimental: true
-          - os: ubuntu
-            ruby: head
-            experimental: true
-          - os: ubuntu
-            ruby: 2.6
-            experimental: false
-            env: COVERAGE=PartialSummary,Coveralls
-    
-    steps:
-    - uses: actions/checkout@v1
-    - uses: ruby/setup-ruby@v1
-      with:
-        ruby-version: ${{matrix.ruby}}
-    
-    - name: Install dependencies
-      run: ${{matrix.env}} bundle install
-    
-    - name: Run tests
-      timeout-minutes: 5
-      run: |
-        ${{matrix.env}} bundle exec rspec

data/.gitignore

@@ -1,13 +0,0 @@
-/.bundle/
-/.yardoc
-/_yardoc/
-/coverage/
-/doc/
-/pkg/
-/spec/reports/
-/tmp/
-
-/gems.locked
-
-# rspec failure tracking
-.rspec_status

data/.rspec

@@ -1,2 +0,0 @@
---format documentation
---require spec_helper

data/README.md

@@ -1,47 +0,0 @@
-# Decode
-
-A Ruby code analysis tool and documentation generator.
-
-[![Development](https://github.com/ioquatix/decode/workflows/Development/badge.svg)](https://github.com/ioquatix/decode/actions?workflow=Development)
-
-## Motivation
-
-As part of my effort to build [better project documentation](https://github.com/socketry/utopia-project), I needed a better code analysis tool. While less featured than some of the more mature alternatives, this library focuses on the needs of documentation generation, including speed, cross-referencing and (eventually) multi-language support.
-
-## Usage
-
-Please see the <a href="https://ioquatix.github.io/decode/">project documentation</a> or run it locally using `bake utopia:project:serve`.
-
-## Contributing
-
-We welcome contributions to this project.
-
-1. Fork it
-2. Create your feature branch (`git checkout -b my-new-feature`)
-3. Commit your changes (`git commit -am 'Add some feature'`)
-4. Push to the branch (`git push origin my-new-feature`)
-5. Create new Pull Request
-
-## License
-
-Released under the MIT license.
-
-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.

data/decode.gemspec

@@ -1,33 +0,0 @@
-
-require_relative 'lib/decode/version'
-
-Gem::Specification.new do |spec|
-	spec.name = "decode"
-	spec.version = Decode::VERSION
-	spec.authors = ["Samuel Williams"]
-	spec.email = ["samuel.williams@oriontransfer.co.nz"]
-	
-	spec.summary = "Code analysis for documentation generation."
-	spec.homepage = "https://github.com/ioquatix/decode"
-	spec.license = "MIT"
-	
-	spec.required_ruby_version = Gem::Requirement.new(">= 2.3.0")
-	
-	# Specify which files should be added to the gem when it is released.
-	# The `git ls-files -z` loads the files in the RubyGem that have been added into git.
-	spec.files = Dir.chdir(File.expand_path('..', __FILE__)) do
-		`git ls-files -z`.split("\x0").reject { |f| f.match(%r{^(docs|test|spec|features)/}) }
-	end
-	
-	spec.executables = spec.files.grep(%r{^exe/}) { |f| File.basename(f) }
-	spec.require_paths = ["lib"]
-	
-	spec.add_dependency "parser"
-	
-	spec.add_development_dependency 'build-files'
-	spec.add_development_dependency 'bake-bundler'
-	spec.add_development_dependency 'utopia-project'
-	spec.add_development_dependency 'covered'
-	spec.add_development_dependency 'bundler'
-	spec.add_development_dependency 'rspec'
-end

data/gems.rb

@@ -1,3 +0,0 @@
-source "https://rubygems.org"
-
-gemspec

data/guides/extract-symbols/extract.rb

@@ -1,26 +0,0 @@
-#!/usr/bin/env ruby
-
-# This example demonstrates how to extract symbols using the index. An instance of {Decode::Index} is used for loading symbols from source code files. These symbols are available as a flat list and as a trie structure. You can look up specific symbols using a reference using {Decode::Index:lookup}.
-require_relative '../../lib/decode/index'
-
-# Firstly, construct the index:
-index = Decode::Index.new
-
-# Then, update the index by loading paths from the file system:
-paths = Dir.glob(File.expand_path("../../lib/**/*.rb", __dir__))
-index.update(paths)
-
-# Finally, you can print out the loaded symbols:
-index.symbols.each do |name, symbol|
-	puts symbol.long_form
-end
-
-# Lookup a specific symbol:
-absolute_reference = Decode::Language::Ruby.reference("Decode::Index:lookup")
-lookup_symbol = index.lookup(absolute_reference).first
-puts lookup_symbol.long_form
-
-# Lookup a method relative to that symbol:
-relative_reference = Decode::Language::Ruby.reference("trie")
-trie_attribute = index.lookup(relative_reference, relative_to: lookup_symbol).first
-puts trie_attribute.long_form