decode 0.25.0 → 0.27.0

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

@@ -1,7 +1,7 @@
 # frozen_string_literal: true
 
 # Released under the MIT License.
-# Copyright, 2020-2025, by Samuel Williams.
+# Copyright, 2020-2026, by Samuel Williams.
 
 require_relative "definition"
 
@@ -18,10 +18,23 @@ module Decode
 					super(*arguments, **options)
 					
 					@super_class = super_class
+					@includes = []
+					@extends = []
+					@prepends = []
 				end
 				
+				# @attribute [String?] The super class name.
 				attr :super_class
 				
+				# @attribute [Array(Symbol)] Modules included into this class.
+				attr :includes
+				
+				# @attribute [Array(Symbol)] Modules extended into this class (adds singleton methods).
+				attr :extends
+				
+				# @attribute [Array(Symbol)] Modules prepended into this class (method lookup precedence).
+				attr :prepends
+				
 				# A class is a container for other definitions.
 				def container?
 					true

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

@@ -34,6 +34,8 @@ module Decode
 					tags["public"] = Comment::Pragma
 					tags["private"] = Comment::Pragma
 					
+					tags["example"] = Comment::Example
+					
 					tags["rbs"] = Comment::RBS
 				end
 				

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

@@ -1,7 +1,7 @@
 # frozen_string_literal: true
 
 # Released under the MIT License.
-# Copyright, 2020-2025, by Samuel Williams.
+# Copyright, 2020-2026, by Samuel Williams.
 
 require_relative "definition"
 
@@ -10,6 +10,24 @@ module Decode
 		module Ruby
 			# A Ruby-specific module.
 			class Module < Definition
+				# Initialize a module with its name and options.
+				def initialize(*arguments, **options)
+					super(*arguments, **options)
+					
+					@includes = []
+					@extends = []
+					@prepends = []
+				end
+				
+				# @attribute [Array(Symbol)] Modules included into this module.
+				attr :includes
+				
+				# @attribute [Array(Symbol)] Modules extended into this module (adds singleton methods).
+				attr :extends
+				
+				# @attribute [Array(Symbol)] Modules prepended into this module (method lookup precedence).
+				attr :prepends
+				
 				# A module is a container for other definitions.
 				def container?
 					true

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

@@ -1,7 +1,7 @@
 # frozen_string_literal: true
 
 # Released under the MIT License.
-# Copyright, 2020-2025, by Samuel Williams.
+# Copyright, 2020-2026, by Samuel Williams.
 
 require "prism"
 
@@ -93,13 +93,13 @@ module Decode
 						path = nested_path_for(node.constant_path)
 						
 						definition = Module.new(path,
-									visibility: :public,
-									comments: comments_for(node),
-									parent: parent,
-									node: node,
-									language: @language,
-									source: source,
-								)
+							visibility: :public,
+							comments: comments_for(node),
+							parent: parent,
+							node: node,
+							language: @language,
+							source: source,
+						)
 						
 						store_definition(parent, path.last.to_sym, definition)
 						yield definition
@@ -114,14 +114,14 @@ module Decode
 						super_class = nested_name_for(node.superclass)
 						
 						definition = Class.new(path,
-									super_class: super_class,
-									visibility: :public, 
-									comments: comments_for(node),
-									parent: parent,
-									node: node,
-									language: @language,
-									source: source,
-								)
+							super_class: super_class,
+							visibility: :public, 
+							comments: comments_for(node),
+							parent: parent,
+							node: node,
+							language: @language,
+							source: source,
+						)
 						
 						store_definition(parent, path.last.to_sym, definition)
 						yield definition
@@ -134,13 +134,13 @@ module Decode
 					when :singleton_class_node
 						if name = singleton_name_for(node)
 							definition = Singleton.new(name,
-										comments: comments_for(node),
-										parent: parent,
-										node: node,
-										language: @language,
-										visibility: :public,
-										source: source
-									)
+								comments: comments_for(node),
+								parent: parent,
+								node: node,
+								language: @language,
+								visibility: :public,
+								source: source
+							)
 							
 							yield definition
 							
@@ -152,23 +152,23 @@ module Decode
 						receiver = receiver_for(node.receiver)
 						
 						definition = Method.new(node.name,
-									visibility: @visibility,
-									comments: comments_for(node),
-									parent: parent,
-									node: node,
-									language: @language,
-									receiver: receiver,
-									source: source,
-								)
+							visibility: @visibility,
+							comments: comments_for(node),
+							parent: parent,
+							node: node,
+							language: @language,
+							receiver: receiver,
+							source: source,
+						)
 						
 						yield definition
 					when :constant_write_node
 						definition = Constant.new(node.name,
-									comments: comments_for(node),
-									parent: parent,
-									node: node,
-									language: @language,
-								)
+							comments: comments_for(node),
+							parent: parent,
+							node: node,
+							language: @language,
+						)
 						
 						store_definition(parent, node.name, definition)
 						yield definition
@@ -176,6 +176,40 @@ module Decode
 						name = node.name
 						
 						case name
+						when :include, :extend, :prepend
+							# Handle mixins inside classes/modules
+							if parent
+								if node.arguments
+									node.arguments.arguments.each do |arg|
+										mod_name = case arg.type
+										when :constant_read_node
+											# Qualify with enclosing namespace if available (e.g. Mixins::Greeting)
+											if parent.parent && parent.parent.respond_to?(:qualified_name)
+												"#{parent.parent.qualified_name}::#{arg.name}"
+											else
+												arg.name.to_s
+											end
+										when :constant_path_node
+											nested_name_for(arg)
+										else
+											# Skip unsupported argument types (e.g., dynamic expressions)
+											nil
+										end
+										if mod_name
+											case name
+											when :include
+												parent.respond_to?(:includes) && parent.includes << mod_name
+											when :extend
+												parent.respond_to?(:extends) && parent.extends << mod_name
+											when :prepend
+												parent.respond_to?(:prepends) && parent.prepends << mod_name
+											end
+										end
+									end
+								end
+							end
+							# Don't treat include/extend as definitions.
+							return
 						when :public, :protected, :private
 							# Handle cases like "private def foo" where method definitions are arguments
 							if node.arguments
@@ -187,13 +221,13 @@ module Decode
 										receiver = receiver_for(argument_node.receiver)
 										
 										definition = Method.new(argument_node.name,
-													visibility: name,
-													comments: comments_for(argument_node),
-													parent: parent,
-													node: argument_node,
-													language: @language,
-													receiver: receiver,
-												)
+											visibility: name,
+											comments: comments_for(argument_node),
+											parent: parent,
+											node: argument_node,
+											language: @language,
+											receiver: receiver,
+										)
 										
 										yield definition
 									end
@@ -217,9 +251,9 @@ module Decode
 							end
 						when :attr, :attr_reader, :attr_writer, :attr_accessor
 							definition = Attribute.new(attribute_name_for(node),
-										comments: comments_for(node),
-										parent: parent, language: @language, node: node
-									)
+								comments: comments_for(node),
+								parent: parent, language: @language, node: node
+							)
 							
 							yield definition
 						when :alias_method
@@ -233,29 +267,29 @@ module Decode
 								old_name = symbol_name_for(old_name_arg)
 								
 								definition = Alias.new(new_name.to_sym, old_name.to_sym,
-											comments: comments_for(node),
-											parent: parent,
-											node: node,
-											language: @language,
-											visibility: @visibility,
-											source: source,
-										)
+									comments: comments_for(node),
+									parent: parent,
+									node: node,
+									language: @language,
+									visibility: @visibility,
+									source: source,
+								)
 								
 								yield definition
 							end
 						else
 							# Check if this call should be treated as a definition
 							# either because it has a @name comment, @attribute comment, or a block
-							has_name_comment = comments_for(node).any? {|comment| comment.match(NAME_ATTRIBUTE)}
+							has_name_comment = comments_for(node).any?{|comment| comment.match(NAME_ATTRIBUTE)}
 							has_attribute_comment = kind_for(node, comments_for(node))
 							has_block = node.block
 							
 							if has_name_comment || has_attribute_comment || has_block
 								definition = Call.new(
-											attribute_name_for(node),
-											comments: comments_for(node),
-											parent: parent, language: @language, node: node
-										)
+									attribute_name_for(node),
+									comments: comments_for(node),
+									parent: parent, language: @language, node: node
+								)
 								
 								yield definition
 								
@@ -265,19 +299,19 @@ module Decode
 								end
 							end
 						end
-					when :alias_method_node
-						# Handle alias new_name old_name syntax
+					when :alias_node, :alias_method_node
+						# Handle `alias new_name old_name` syntax:
 						new_name = node.new_name.unescaped
 						old_name = node.old_name.unescaped
 						
 						definition = Alias.new(new_name.to_sym, old_name.to_sym,
-									comments: comments_for(node),
-									parent: parent,
-									node: node,
-									language: @language,
-									visibility: @visibility,
-									source: source,
-								)
+							comments: comments_for(node),
+							parent: parent,
+							node: node,
+							language: @language,
+							visibility: @visibility,
+							source: source,
+						)
 						
 						yield definition
 					when :if_node
@@ -404,8 +438,8 @@ module Decode
 					saved_visibility = @visibility
 					@visibility = visibility
 					yield
-						ensure
-							@visibility = saved_visibility
+				ensure
+					@visibility = saved_visibility
 				end
 				
 				NAME_ATTRIBUTE = /\A@name\s+(?<value>.*?)\Z/
@@ -550,20 +584,20 @@ module Decode
 								# Start a new segment with these comments
 								yield current_segment if current_segment
 								current_segment = Segment.new(
-											preceding_comments.map{|comment| comment.location.slice.sub(/^#[\s\t]?/, "")},
-											@language,
-											statement
-										)
+									preceding_comments.map{|comment| comment.location.slice.sub(/^#[\s\t]?/, "")},
+									@language,
+									statement
+								)
 							elsif current_segment
 								# Extend current segment with this statement
 								current_segment.expand(statement)
 							else
 								# Start a new segment without comments
 								current_segment = Segment.new(
-											[],
-											@language,
-											statement
-										)
+									[],
+									@language,
+									statement
+								)
 							end
 						end
 						
@@ -571,10 +605,10 @@ module Decode
 					else
 						# One top level segment:
 						segment = Segment.new(
-									[],
-									@language,
-									node
-								)
+							[],
+							@language,
+							node
+						)
 						
 						yield segment
 					end

data/lib/decode/rbs/class.rb

@@ -1,7 +1,7 @@
 # frozen_string_literal: true
 
 # Released under the MIT License.
-# Copyright, 2025, by Samuel Williams.
+# Copyright, 2025-2026, by Samuel Williams.
 
 require "rbs"
 require_relative "wrapper"
@@ -35,6 +35,7 @@ module Decode
 						name: generic.to_sym,
 						variance: nil,
 						upper_bound: nil,
+						lower_bound: nil,
 						location: nil
 					)
 				end
@@ -51,10 +52,10 @@ module Decode
 				# Extract super class if present:
 				super_class = if @definition.super_class
 					::RBS::AST::Declarations::Class::Super.new(
-								name: qualified_name_to_rbs(@definition.super_class),
-								args: [],
-								location: nil
-							)
+						name: qualified_name_to_rbs(@definition.super_class),
+						args: [],
+						location: nil
+					)
 				end
 				
 				# Create the class declaration with generics:

data/lib/decode/rbs/method.rb

@@ -1,7 +1,7 @@
 # frozen_string_literal: true
 
 # Released under the MIT License.
-# Copyright, 2025, by Samuel Williams.
+# Copyright, 2025-2026, by Samuel Williams.
 
 require "rbs"
 require "console"
@@ -103,15 +103,15 @@ module Decode
 				kind = @definition.receiver ? :singleton : :instance
 				
 				::RBS::AST::Members::MethodDefinition.new(
-				name: method_name.to_sym,
-				kind: kind,
-				overloads: overloads,
-				annotations: [],
-				location: nil,
-				comment: comment,
-				overloading: false,
-				visibility: @definition.visibility || :public
-			)
+					name: method_name.to_sym,
+					kind: kind,
+					overloads: overloads,
+					annotations: [],
+					location: nil,
+					comment: comment,
+					overloading: false,
+					visibility: @definition.visibility || :public
+				)
 			end
 			
 			# Build a complete RBS function type from AST information.
@@ -265,7 +265,7 @@ module Decode
 				
 				# Find @parameter tags (but not @option tags, which are handled separately):
 				param_tags = documentation.filter(Decode::Comment::Parameter).to_a
-				param_tags = param_tags.reject {|tag| tag.is_a?(Decode::Comment::Option)}
+				param_tags = param_tags.reject{|tag| tag.is_a?(Decode::Comment::Option)}
 				return [] if param_tags.empty?
 				
 				param_tags.map do |tag|

data/lib/decode/rbs/module.rb

@@ -1,7 +1,7 @@
 # frozen_string_literal: true
 
 # Released under the MIT License.
-# Copyright, 2025, by Samuel Williams.
+# Copyright, 2025-2026, by Samuel Williams.
 
 require "rbs"
 require_relative "wrapper"
@@ -62,11 +62,11 @@ module Decode
 					type = ::Decode::RBS::Type.parse(type_string)
 					
 					::RBS::AST::Declarations::Constant.new(
-					name: constant_definition.name.to_sym,
-					type: type,
-					location: nil,
-					comment: nil
-				)
+						name: constant_definition.name.to_sym,
+						type: type,
+						location: nil,
+						comment: nil
+					)
 				end
 			end
 			

data/lib/decode/rbs/type.rb

@@ -1,7 +1,7 @@
 # frozen_string_literal: true
 
 # Released under the MIT License.
-# Copyright, 2024, by Samuel Williams.
+# Copyright, 2025-2026, by Samuel Williams.
 
 require "rbs"
 require "console"
@@ -21,10 +21,10 @@ module Decode
 					true
 				when ::RBS::Types::Union
 					# Type | nil form - recursively check all union members
-					rbs_type.types.any? {|type| nullable?(type)}
+					rbs_type.types.any?{|type| nullable?(type)}
 				when ::RBS::Types::Tuple
 					# [Type] form - recursively check all tuple elements
-					rbs_type.types.any? {|type| nullable?(type)}
+					rbs_type.types.any?{|type| nullable?(type)}
 				when ::RBS::Types::Bases::Nil
 					# Direct nil type
 					true
@@ -49,4 +49,4 @@ module Decode
 			end
 		end
 	end
-end 
+end 

data/lib/decode/scope.rb

@@ -1,7 +1,7 @@
 # frozen_string_literal: true
 
 # Released under the MIT License.
-# Copyright, 2020-2024, by Samuel Williams.
+# Copyright, 2020-2025, by Samuel Williams.
 
 require_relative "definition"
 

data/lib/decode/version.rb

@@ -5,5 +5,5 @@
 
 module Decode
 	# @constant [String] The version of the gem.
-	VERSION = "0.25.0"
+	VERSION = "0.27.0"
 end

data/license.md

@@ -1,6 +1,6 @@
 # MIT License
 
-Copyright, 2020-2025, by Samuel Williams.  
+Copyright, 2020-2026, by Samuel Williams.  
 
 Permission is hereby granted, free of charge, to any person obtaining a copy
 of this software and associated documentation files (the "Software"), to deal

data/readme.md

@@ -14,14 +14,24 @@ Please see the [project documentation](https://socketry.github.io/decode/) for m
 
   - [Getting Started](https://socketry.github.io/decode/guides/getting-started/index) - This guide explains how to use `decode` for source code analysis.
 
-  - [Code Coverage](https://socketry.github.io/decode/guides/code-coverage/index) - This guide explains how to compute documentation code coverage.
+  - [Documentation Coverage](https://socketry.github.io/decode/guides/documentation-coverage/index) - This guide explains how to test and monitor documentation coverage in your Ruby projects using the Decode gem's built-in bake tasks.
 
   - [Extract Symbols](https://socketry.github.io/decode/guides/extract-symbols/index) - This example demonstrates how to extract symbols using the index. An instance of <code class="language-ruby">Decode::Index</code> 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 <code class="language-ruby">Decode::Index\#lookup</code>.
 
+  - [Ruby Documentation](https://socketry.github.io/decode/guides/ruby-documentation/index) - This guide covers documentation practices and pragmas supported by the Decode gem for documenting Ruby code. These pragmas provide structured documentation that can be parsed and used to generate API documentation and achieve complete documentation coverage.
+
 ## Releases
 
 Please see the [project releases](https://socketry.github.io/decode/releases/index) for all releases.
 
+### v0.27.0
+
+    - Add `decode:documentation:markdown` bake task for generating LLM-optimized Markdown documentation.
+
+### v0.26.0
+
+  - Add support for `@example` pragmas in Ruby documentation comments.
+
 ### v0.25.0
 
   - Singleton classes are not relevant for coverage, so they are now ignored by the coverage reporter.
@@ -54,6 +64,22 @@ We welcome contributions to this project.
 4.  Push to the branch (`git push origin my-new-feature`).
 5.  Create new Pull Request.
 
+### Running Tests
+
+To run the test suite:
+
+``` shell
+bundle exec sus
+```
+
+### Making Releases
+
+To make a new release:
+
+``` shell
+bundle exec bake gem:release:patch # or minor or major
+```
+
 ### Developer Certificate of Origin
 
 In order to protect users of this project, we require all contributors to comply with the [Developer Certificate of Origin](https://developercertificate.org/). This ensures that all contributions are properly licensed and attributed.

data/releases.md

@@ -1,5 +1,13 @@
 # Releases
 
+## v0.27.0
+
+    - Add `decode:documentation:markdown` bake task for generating LLM-optimized Markdown documentation.
+
+## v0.26.0
+
+  - Add support for `@example` pragmas in Ruby documentation comments.
+
 ## v0.25.0
 
   - Singleton classes are not relevant for coverage, so they are now ignored by the coverage reporter.

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: decode
 version: !ruby/object:Gem::Version
-  version: 0.25.0
+  version: 0.27.0
 platform: ruby
 authors:
 - Samuel Williams
@@ -71,15 +71,17 @@ extensions: []
 extra_rdoc_files: []
 files:
 - agent.md
+- bake/decode/documentation.rb
 - bake/decode/index.rb
 - bake/decode/rbs.rb
-- context/coverage.md
+- context/documentation-coverage.md
 - context/getting-started.md
+- context/index.yaml
 - context/ruby-documentation.md
-- context/types.md
 - lib/decode.rb
 - lib/decode/comment/attribute.rb
 - lib/decode/comment/constant.rb
+- lib/decode/comment/example.rb
 - lib/decode/comment/node.rb
 - lib/decode/comment/option.rb
 - lib/decode/comment/parameter.rb
@@ -149,14 +151,14 @@ required_ruby_version: !ruby/object:Gem::Requirement
   requirements:
   - - ">="
     - !ruby/object:Gem::Version
-      version: '3.2'
+      version: '3.3'
 required_rubygems_version: !ruby/object:Gem::Requirement
   requirements:
   - - ">="
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 3.6.9
+rubygems_version: 4.0.6
 specification_version: 4
 summary: Code analysis for documentation generation.
 test_files: []