ffi-clang 0.13.0 → 0.14.0

data/lib/ffi/clang/translation_unit.rb

@@ -3,68 +3,94 @@
 # Released under the MIT License.
 # Copyright, 2010, by Jari Bakken.
 # Copyright, 2012, by Hal Brodigan.
-# Copyright, 2013-2022, by Samuel Williams.
+# Copyright, 2013-2025, by Samuel Williams.
 # Copyright, 2013, by Garry Marshall.
 # Copyright, 2014, by Masahiro Sano.
 # Copyright, 2014, by Greg Hazel.
 # Copyright, 2019, by Michael Metivier.
 # Copyright, 2022, by Motonori Iwamuro.
 
-require_relative 'lib/translation_unit'
-require_relative 'lib/inclusions'
-require_relative 'cursor'
-require_relative 'file'
-require_relative 'token'
+require_relative "lib/translation_unit"
+require_relative "lib/inclusions"
+require_relative "cursor"
+require_relative "file"
+require_relative "token"
+require_relative "error"
 
 module FFI
 	module Clang
+		# Represents a single translation unit (a compiled source file with its dependencies).
 		class TranslationUnit < AutoPointer
+			# Initialize a translation unit with a pointer and parent index.
+			# @parameter pointer [FFI::Pointer] The translation unit pointer.
+			# @parameter index [Index] The parent index that created this translation unit.
 			def initialize(pointer, index)
 				super pointer
 				@index = index
 			end
-
+			
+			# Release the translation unit pointer.
+			# @parameter pointer [FFI::Pointer] The translation unit pointer to release.
 			def self.release(pointer)
 				Lib.dispose_translation_unit(pointer)
 			end
-
+			
+			# Get the default editing translation unit options.
+			# @returns [Array(Symbol)] The default editing options.
 			def self.default_editing_translation_unit_options
 				bitmask = Lib.default_editing_translation_unit_options
 				Lib.opts_from Lib::TranslationUnitFlags, bitmask
 			end
-
+			
+			# Get the default save options for this translation unit.
+			# @returns [Array(Symbol)] The default save options.
 			def default_save_options
 				bitmask = Lib.default_save_options(self)
 				Lib.opts_from Lib::SaveTranslationUnitFlags, bitmask
 			end
-
+			
+			# Save the translation unit to a file.
+			# @parameter filename [String] The path where the translation unit should be saved.
+			# @parameter opts [Hash] Save options.
+			# @raises [Error] If saving fails.
 			def save(filename, opts = {})
 				ret = Lib.save_translation_unit(self, filename, 0)
 				sym = Lib::SaveError[ret]
 				raise Error, "unknown return values: #{ret} #{sym.inspect}" unless sym
 				raise Error, "save error: #{sym.inspect}, filename: #{filename}" if sym != :none
 			end
-
+			
+			# Get the default reparse options for this translation unit.
+			# @returns [Array(Symbol)] The default reparse options.
 			def default_reparse_options
 				bitmask = Lib.default_save_options(self)
 				Lib.opts_from Lib::ReparseFlags, bitmask
 			end
-
+			
+			# Reparse the translation unit with updated file contents.
+			# @parameter unsaved [Array(UnsavedFile)] Unsaved file buffers.
+			# @parameter opts [Hash] Reparse options.
+			# @raises [Error] If reparsing fails.
 			def reparse(unsaved = [], opts = {})
 				unsaved_files = UnsavedFile.unsaved_pointer_from(unsaved)
 				if Lib.reparse_translation_unit(self, unsaved.size, unsaved_files, 0) != 0
 					raise Error, "reparse error"
 				end
 			end
-
+			
+			# Get all diagnostics for this translation unit.
+			# @returns [Array(Diagnostic)] Array of diagnostics.
 			def diagnostics
 				n = Lib.get_num_diagnostics(self)
-			
+				
 				n.times.map do |i|
 					Diagnostic.new(self, Lib.get_diagnostic(self, i))
 				end
 			end
-
+			
+			# Get a cursor for the translation unit or at a specific location.
+			# @parameter location [SourceLocation | Nil] The location for the cursor, or `nil` for the root cursor.
+			# @returns [Cursor] The cursor at the specified location or the root cursor.
 			def cursor(location = nil)
 				if location.nil?
 					Cursor.new Lib.get_translation_unit_cursor(self), self
@@ -72,15 +98,27 @@ module FFI
 					Cursor.new Lib.get_cursor(self, location.location), self
 				end
 			end
-
+			
+			# Get a source location by file, line, and column.
+			# @parameter file [File] The file object.
+			# @parameter line [Integer] The line number (1-indexed).
+			# @parameter column [Integer] The column number (1-indexed).
+			# @returns [ExpansionLocation] The source location.
 			def location(file, line, column)
 				ExpansionLocation.new Lib.get_location(self, file, line, column)
 			end
-
+			
+			# Get a source location by file and byte offset.
+			# @parameter file [File] The file object.
+			# @parameter offset [Integer] The byte offset from the start of the file.
+			# @returns [ExpansionLocation] The source location.
 			def location_offset(file, offset)
 				ExpansionLocation.new Lib.get_location_offset(self, file, offset)
 			end
-
+			
+			# Get a file object from this translation unit.
+			# @parameter file_name [String | Nil] The file name, or `nil` to get the main file.
+			# @returns [File] The file object.
 			def file(file_name = nil)
 				if file_name.nil?
 					File.new(Lib.get_file(self, spelling), self)
@@ -88,22 +126,36 @@ module FFI
 					File.new(Lib.get_file(self, file_name), self)
 				end
 			end
-
+			
+			# Get the spelling (filename) of this translation unit.
+			# @returns [String] The filename of the translation unit.
 			def spelling
 				Lib.extract_string Lib.get_translation_unit_spelling(self)
 			end
-
+			
+			# Get resource usage information for this translation unit.
+			# @returns [ResourceUsage] Resource usage statistics.
 			def resource_usage
 				FFI::Clang::TranslationUnit::ResourceUsage.new Lib.resource_usage(self)
 			end
-
+			
+			# Tokenize a source range.
+			# @parameter range [SourceRange] The source range to tokenize.
+			# @returns [Tokens] Collection of tokens in the range.
 			def tokenize(range)
 				token_ptr = MemoryPointer.new :pointer
 				uint_ptr = MemoryPointer.new :uint
 				Lib.tokenize(self, range.range, token_ptr, uint_ptr)
 				Tokens.new(token_ptr.get_pointer(0), uint_ptr.get_uint(0), self)
 			end
-
+			
+			# Perform code completion at a specific location.
+			# @parameter source_file [String] The path to the source file.
+			# @parameter line [Integer] The line number for code completion.
+			# @parameter column [Integer] The column number for code completion.
+			# @parameter unsaved [Array(UnsavedFile)] Unsaved file buffers.
+			# @parameter opts [Array(Symbol) | Nil] Code completion options, or `nil` for defaults.
+			# @returns [CodeCompletion::Results] The code completion results.
 			def code_complete(source_file, line, column, unsaved = [], opts = nil)
 				opts = CodeCompletion.default_code_completion_options if opts.nil?
 				unsaved_files = UnsavedFile.unsaved_pointer_from(unsaved)
@@ -111,23 +163,29 @@ module FFI
 				ptr = Lib.code_complete_at(self, source_file, line, column, unsaved_files, unsaved.length, option_bitmask)
 				CodeCompletion::Results.new ptr, self
 			end
-
+			
+			# Iterate over all file inclusions in this translation unit.
+			# @yields {|file, locations| ...} Each inclusion with its file path and stack.
+			# 	@parameter file [String] The included file path.
+			# 	@parameter locations [Array(SourceLocation)] The inclusion stack.
 			def inclusions(&block)
 				adapter = Proc.new do |included_file, inclusion_stack, include_len, unused|
 					file = Lib.extract_string Lib.get_file_name(included_file)
 					cur_ptr = inclusion_stack
 					inclusions = []
-					include_len.times {
-						inclusions << SourceLocation.new(Lib::CXSourceLocation.new(cur_ptr))
-						cur_ptr += Lib::CXSourceLocation.size
+					include_len.times {inclusions << SourceLocation.new(Lib::CXSourceLocation.new(cur_ptr))
+																								cur_ptr += Lib::CXSourceLocation.size
 					}
 					block.call file, inclusions
 				end
 				
 				Lib.get_inclusions(self, adapter, nil)
 			end
-
+			
+			# Represents resource usage statistics for a translation unit.
 			class ResourceUsage < AutoPointer
+				# Initialize resource usage from a CXTUResourceUsage structure.
+				# @parameter resource_usage [Lib::CXTUResourceUsage] The resource usage structure.
 				def initialize(resource_usage)
 					# CXResourceUsage is returned by value and should be freed explicitly.
 					# Get FFI::pointer of the data so that the data is handled by AutoPointer.
@@ -135,22 +193,28 @@ module FFI
 					super(pointer)
 					@resource_usage = resource_usage
 				end
-
+				
+				# Release the resource usage pointer.
+				# @parameter pointer [FFI::Pointer] The resource usage pointer to release.
 				def self.release(pointer)
 					# clang_disposeCXTUResourceUsage requires value type, so create it by pointer
 					Lib.dispose_resource_usage(Lib::CXTUResourceUsage.new(pointer))
 				end
-
+				
+				# Get the name of a resource usage kind.
+				# @parameter kind [Symbol] The resource usage kind.
+				# @returns [String] The name of the resource kind.
 				def self.name(kind)
 					Lib.resource_usage_name(kind)
 				end
-
+				
+				# Get all resource usage entries.
+				# @returns [Array(Lib::CXTUResourceUsageEntry)] The resource usage entries.
 				def entries
 					ary = []
 					ptr = @resource_usage[:entries]
-					@resource_usage[:numEntries].times {
-						ary << Lib::CXTUResourceUsageEntry.new(ptr)
-						ptr += Lib::CXTUResourceUsageEntry.size
+					@resource_usage[:numEntries].times {ary << Lib::CXTUResourceUsageEntry.new(ptr)
+																																									ptr += Lib::CXTUResourceUsageEntry.size
 					}
 					ary
 				end

data/lib/ffi/clang/types/array.rb

@@ -1,11 +1,25 @@
+# frozen_string_literal: true
+
+# Released under the MIT License.
+# Copyright, 2024, by Charlie Savage.
+# Copyright, 2025, by Samuel Williams.
+
 module FFI
 	module Clang
+		# Type system classes for representing C/C++ types.
+		# @namespace
 		module Types
+			# Represents an array type.
+			# This includes constant arrays, incomplete arrays, variable arrays, and dependent-sized arrays.
 			class Array < Type
+				# Get the element type of this array.
+				# @returns [Type] The type of elements in this array.
 				def element_type
 					Type.create Lib.get_array_element_type(@type), @translation_unit
 				end
-
+				
+				# Get the size of this array.
+				# @returns [Integer] The number of elements in the array, or -1 if the size is not available.
 				def size
 					Lib.get_array_size(@type)
 				end

data/lib/ffi/clang/types/elaborated.rb

@@ -1,26 +1,41 @@
+# frozen_string_literal: true
+
+# Released under the MIT License.
+# Copyright, 2024-2025, by Charlie Savage.
+# Copyright, 2025, by Samuel Williams.
+
 module FFI
 	module Clang
 		module Types
+			# Represents an elaborated type (e.g., struct, union, enum with an elaborated type specifier).
+			# Elaborated types may include type qualifiers and nested name specifiers.
 			class Elaborated < Type
+				# Get the named type that this elaborated type refers to.
+				# @returns [Type] The underlying named type.
 				def named_type
 					Type.create Lib.get_named_type(@type), @translation_unit
 				end
-
-				# Example anonymous union where `u` is an elaborated type
+				
+				# Check if this is an anonymous elaborated type.
+				# Example anonymous union where `u` is an elaborated type:
 				#
 				#	 typedef struct {
 				#		 union {
 				#			 int idata;
 				#		 } u;
 				#	 } SomeStruct;
+				#
+				# @returns [Boolean] True if this elaborated type is anonymous.
 				def anonymous?
 					self.declaration.anonymous?
 				end
-
+				
+				# Check if this elaborated type is a pointer in its canonical form.
+				# @returns [Boolean] True if the canonical type is a pointer.
 				def pointer?
 					self.canonical.is_a?(Pointer)
 				end
 			end
 		end
 	end
-end
+end

data/lib/ffi/clang/types/function.rb

@@ -1,43 +1,68 @@
+# frozen_string_literal: true
+
+# Released under the MIT License.
+# Copyright, 2024, by Charlie Savage.
+# Copyright, 2025, by Samuel Williams.
+
 module FFI
 	module Clang
 		module Types
+			# Represents a function type.
+			# This includes functions with and without prototypes.
 			class Function < Type
 				include Enumerable
-
+				
+				# Check if this function is variadic.
+				# @returns [Boolean] True if the function accepts a variable number of arguments.
 				def variadic?
 					Lib.is_function_type_variadic(@type) != 0
 				end
-
+				
+				# Get the number of arguments this function takes.
+				# @returns [Integer] The number of arguments.
 				def args_size
 					Lib.get_num_arg_types(@type)
 				end
-
+				
+				# Get the type of a specific argument.
+				# @parameter i [Integer] The zero-based argument index.
+				# @returns [Type] The type of the argument at the specified index.
 				def arg_type(i)
 					Type.create Lib.get_arg_type(@type, i), @translation_unit
 				end
-
+				
+				# Iterate over all argument types or get an enumerator.
+				# @yields {|type| ...} Yields each argument type if a block is given.
+				# 	@parameter type [Type] An argument type.
+				# @returns [Enumerator, self] An enumerator if no block is given, self otherwise.
 				def arg_types
 					return to_enum(:arg_types) unless block_given?
-
+					
 					self.args_size.times do |i|
 						yield self.arg_type(i)
 					end
-
+					
 					self
 				end
-
+				
+				# Get the return type of this function.
+				# @returns [Type] The function's return type.
 				def result_type
 					Type.create Lib.get_result_type(@type), @translation_unit
 				end
-
+				
+				# Get the calling convention of this function.
+				# @returns [Symbol] The calling convention (e.g., :calling_conv_c, :calling_conv_x86_stdcall).
 				def calling_conv
 					Lib.get_fuction_type_calling_conv(@type)
 				end
-
+				
+				# Get the exception specification type for this function.
+				# @returns [Symbol] The exception specification type (e.g., :exception_spec_none, :exception_spec_basic_noexcept).
 				def exception_specification
 					Lib.get_exception_specification_type(@type)
 				end
 			end
 		end
 	end
-end
+end

data/lib/ffi/clang/types/pointer.rb

@@ -1,15 +1,29 @@
+# frozen_string_literal: true
+
+# Released under the MIT License.
+# Copyright, 2024, by Charlie Savage.
+# Copyright, 2025, by Samuel Williams.
+
 module FFI
 	module Clang
 		module Types
+			# Represents a pointer type.
+			# This includes regular pointers, block pointers, Objective-C object pointers, and member pointers.
 			class Pointer < Type
+				# Get the type that this pointer points to.
+				# @returns [Type] The pointee type.
 				def pointee
 					Type.create Lib.get_pointee_type(@type), @translation_unit
 				end
-
+				
+				# Check if this is a function pointer.
+				# @returns [Boolean] True if this pointer points to a function.
 				def function?
 					self.pointee.is_a?(Types::Function)
 				end
-
+				
+				# Get the class type for member pointers.
+				# @returns [Type, nil] The class type if this is a member pointer, nil otherwise.
 				def class_type
 					if self.kind == :type_member_pointer
 						Type.create Lib.type_get_class_type(@type), @translation_unit
@@ -17,16 +31,18 @@ module FFI
 						nil
 					end
 				end
-
+				
+				# Check if this pointer references a forward declaration.
+				# @returns [Boolean] True if this pointer points to a forward-declared type.
 				def forward_declaration?
 					# Is this a pointer to a record (struct or union) that referenced
 					# a forward declaration at the point of its inclusion in the translation unit?
 					if !self.function? && self.pointee.is_a?(Types::Elaborated) &&
-						 self.pointee.canonical.is_a?(Types::Record)
-
+							self.pointee.canonical.is_a?(Types::Record)
+						
 						# Get the universal symbol reference
 						usr = self.pointee.canonical.declaration.usr
-
+						
 						# Now does that same usr occur earlier in the file?
 						first_declaration, _ = self.translation_unit.cursor.find do |child, parent|
 							child.usr == usr
@@ -39,4 +55,4 @@ module FFI
 			end
 		end
 	end
-end
+end

data/lib/ffi/clang/types/record.rb

@@ -1,23 +1,38 @@
+# frozen_string_literal: true
+
+# Released under the MIT License.
+# Copyright, 2024, by Charlie Savage.
+# Copyright, 2025, by Samuel Williams.
+
 module FFI
 	module Clang
 		module Types
+			# Represents a record type (struct or union).
 			class Record < Type
+				# Get the byte offset of a field within this record.
+				# @parameter field [String] The name of the field.
+				# @returns [Integer] The byte offset of the field, or -1 if not found.
 				def offsetof(field)
 					Lib.type_get_offset_of(@type, field)
 				end
-
+				
+				# Check if this is an anonymous record.
+				# @returns [Boolean] True if this record is unnamed/anonymous.
 				def anonymous?
 					self.spelling.match(/unnamed/)
 				end
-
+				
+				# Get the kind of record (struct or union).
+				# @returns [Symbol] Either :struct or :union.
+				# @raises [RuntimeError] If the record type cannot be determined.
 				def record_type
 					case self.spelling
-						when /struct/
-							:struct
-						when /union/
-							:union
-						else
-							raise("Unknown record type: #{self.spelling}")
+					when /struct/
+						:struct
+					when /union/
+						:union
+					else
+						raise("Unknown record type: #{self.spelling}")
 					end
 				end
 			end