ffi-clang 0.13.0 → 0.14.0

data/lib/ffi/clang/diagnostic.rb

@@ -3,96 +3,130 @@
 # Released under the MIT License.
 # Copyright, 2010, by Jari Bakken.
 # Copyright, 2012, by Hal Brodigan.
-# Copyright, 2013-2024, by Samuel Williams.
+# Copyright, 2013-2025, by Samuel Williams.
 # Copyright, 2013, by Garry Marshall.
 # Copyright, 2014, by Masahiro Sano.
 # Copyright, 2023, by Charlie Savage.
 
-require_relative 'lib/diagnostic'
-require_relative 'source_range'
+require_relative "lib/diagnostic"
+require_relative "source_range"
 
 module FFI
 	module Clang
+		# Represents a diagnostic message from the compiler.
 		class Diagnostic < AutoPointer
+			# Get the default diagnostic display options.
+			# @returns [Array(Symbol)] The default display options.
 			def self.default_display_opts
 				Lib.opts_from(Lib::DiagnosticDisplayOptions, Lib.default_diagnostic_display_options)
 			end
-
+			
+			# Initialize a diagnostic.
+			# @parameter translation_unit [TranslationUnit] The parent translation unit.
+			# @parameter pointer [FFI::Pointer] The diagnostic pointer.
 			def initialize(translation_unit, pointer)
 				super pointer
-
+				
 				@translation_unit = translation_unit
 			end
-
+			
+			# Release the diagnostic pointer.
+			# @parameter pointer [FFI::Pointer] The pointer to release.
 			def self.release(pointer)
 				Lib.dispose_diagnostic(pointer)
 			end
-
+			
+			# Format the diagnostic as a string.
+			# @parameter opts [Hash] Display options.
+			# @returns [String] The formatted diagnostic.
 			def format(opts = {})
 				cxstring = Lib.format_diagnostic(self, display_opts(opts))
 				Lib.extract_string cxstring
 			end
-
+			
+			# Get the severity of the diagnostic.
+			# @returns [Symbol] The severity level.
 			def severity
 				Lib.get_diagnostic_severity self
 			end
-
+			
+			# Get the diagnostic message text.
+			# @returns [String] The diagnostic spelling.
 			def spelling
 				Lib.get_string Lib.get_diagnostic_spelling(self)
 			end
-
+			
+			# Get the source location of the diagnostic.
+			# @returns [ExpansionLocation] The diagnostic location.
 			def location
 				sl = Lib.get_diagnostic_location(self)
 				ExpansionLocation.new sl
 			end
-
+			
+			# Get fix-it hints for the diagnostic.
+			# @returns [Array(Hash)] Array of fix-its with `:text` and `:range` keys.
 			def fixits
 				n = Lib.get_diagnostic_num_fix_its(self)
-				n.times.map { |i|
-				ptr = MemoryPointer.new Lib::CXSourceRange
+				n.times.map {|i|
+					ptr = MemoryPointer.new Lib::CXSourceRange
 					replace_text = Lib.extract_string(Lib.get_diagnostic_fix_it(self, i, ptr))
 					{text: replace_text, range: SourceRange.new(ptr)}
 				}
 			end
-
+			
+			# Get the source ranges associated with the diagnostic.
+			# @returns [Array(SourceRange)] Array of source ranges.
 			def ranges
 				n = Lib.get_diagnostic_num_ranges(self)
 				
 				n.times.map {|i| SourceRange.new Lib.get_diagnostic_range(self, i)}
 			end
-
+			
+			# Get child diagnostics.
+			# @returns [Array(Diagnostic)] Array of child diagnostics.
 			def children
 				diagnostic_set = Lib.get_child_diagnostics(self)
 				num_diagnostics = Lib.get_num_diagnostics_in_set(diagnostic_set)
-				num_diagnostics.times.map { |i|
+				num_diagnostics.times.map {|i|
 					Diagnostic.new(@translation_unit, Lib.get_diagnostic_in_set(diagnostic_set, i))
 				}
 			end
-
+			
+			# Get the compiler option that enables this diagnostic.
+			# @returns [String] The enable option.
 			def enable_option
 				Lib.extract_string Lib.get_diagnostic_option(self, nil)
 			end
-
+			
+			# Get the compiler option that disables this diagnostic.
+			# @returns [String] The disable option.
 			def disable_option
 				ptr = MemoryPointer.new Lib::CXString
 				Lib.get_diagnostic_option(self, ptr)
 				Lib.extract_string ptr
 			end
-
+			
+			# Get the category text for the diagnostic.
+			# @returns [String] The category text.
 			def category
 				Lib.extract_string Lib.get_diagnostic_category_text(self)
 			end
-
+			
+			# Get the category ID for the diagnostic.
+			# @returns [Integer] The category ID.
 			def category_id
 				Lib.get_diagnostic_category(self)
 			end
-
+			
+			# Get a string representation of the diagnostic.
+			# @returns [String] The diagnostic string.
 			def inspect
 				"#{self.location}: #{self.format}"
 			end
-
+			
 			private
-
+			
+			# @private
 			def display_opts(opts)
 				if opts.empty?
 					Lib.default_diagnostic_display_options

data/lib/ffi/clang/error.rb

@@ -0,0 +1,12 @@
+# frozen_string_literal: true
+
+# Released under the MIT License.
+# Copyright, 2025, by Samuel Williams.
+
+module FFI
+	module Clang
+		# Represents an error that occurred during libclang operations.
+		class Error < StandardError
+		end
+	end
+end

data/lib/ffi/clang/file.rb

@@ -2,48 +2,67 @@
 
 # Released under the MIT License.
 # Copyright, 2014, by Masahiro Sano.
-# Copyright, 2014-2022, by Samuel Williams.
+# Copyright, 2014-2025, by Samuel Williams.
 
-require_relative 'lib/file'
+require_relative "lib/file"
 
 module FFI
 	module Clang
+		# Represents a file in a translation unit.
 		class File < Pointer
+			# @attribute [TranslationUnit] The translation unit this file belongs to.
 			attr_reader :translation_unit
-
+			
+			# Initialize a file with a pointer and translation unit.
+			# @parameter pointer [FFI::Pointer] The file pointer.
+			# @parameter translation_unit [TranslationUnit] The parent translation unit.
 			def initialize(pointer, translation_unit)
 				super pointer
 				@translation_unit = translation_unit
-
+				
 				pointer = MemoryPointer.new(Lib::CXFileUniqueID)
 				Lib.get_file_unique_id(self, pointer)
 				@unique_id = Lib::CXFileUniqueID.new(pointer)
 			end
-
+			
+			# Get the file name as a string.
+			# @returns [String] The file name.
 			def to_s
 				name
 			end
-
+			
+			# Get the file name.
+			# @returns [String] The file name.
 			def name
 				Lib.extract_string Lib.get_file_name(self)
 			end
-
+			
+			# Get the file modification time.
+			# @returns [Time] The file modification time.
 			def time
 				Time.at(Lib.get_file_time(self))
 			end
-
+			
+			# Check if the file has include guards.
+			# @returns [Boolean] True if the file is include guarded.
 			def include_guarded?
 				Lib.is_file_multiple_include_guarded(@translation_unit, self) != 0
 			end
-
+			
+			# Get the device ID of the file.
+			# @returns [Integer] The device ID.
 			def device
 				@unique_id[:device]
 			end
-
+			
+			# Get the inode number of the file.
+			# @returns [Integer] The inode number.
 			def inode
 				@unique_id[:inode]
 			end
-
+			
+			# Get the modification time from the unique ID.
+			# @returns [Time] The modification time.
 			def modification
 				Time.at(@unique_id[:modification])
 			end

data/lib/ffi/clang/index.rb

@@ -3,62 +3,86 @@
 # Released under the MIT License.
 # Copyright, 2010, by Jari Bakken.
 # Copyright, 2012, by Hal Brodigan.
-# Copyright, 2013-2024, by Samuel Williams.
+# Copyright, 2013-2025, by Samuel Williams.
 # Copyright, 2013, by Carlos Martín Nieto.
 # Copyright, 2013, by Dave Wilkinson.
 # Copyright, 2013, by Takeshi Watanabe.
 # Copyright, 2014, by Masahiro Sano.
 # Copyright, 2023, by Charlie Savage.
 
-require_relative 'lib/index'
+require_relative "lib/index"
+require_relative "error"
 
 module FFI
 	module Clang
+		# Represents a libclang index that manages translation units and provides a top-level context for parsing.
 		class Index < AutoPointer
+			# Initialize a new index for managing translation units.
+			# @parameter exclude_declarations [Boolean] Whether to exclude declarations from PCH.
+			# @parameter display_diagnostics [Boolean] Whether to display diagnostics during parsing.
 			def initialize(exclude_declarations = true, display_diagnostics = false)
 				super Lib.create_index(exclude_declarations ? 1 : 0, display_diagnostics ? 1 : 0)
 			end
-
+			
+			# Release the index pointer.
+			# @parameter pointer [FFI::Pointer] The index pointer to release.
 			def self.release(pointer)
 				Lib.dispose_index(pointer)
 			end
-
+			
+			# Parse a source file and create a translation unit.
+			# @parameter source_file [String] The path to the source file to parse.
+			# @parameter command_line_args [Array(String) | String | Nil] Compiler arguments for parsing.
+			# @parameter unsaved [Array(UnsavedFile)] Unsaved file buffers.
+			# @parameter opts [Hash] Parsing options as a hash of flags.
+			# @returns [TranslationUnit] The parsed translation unit.
+			# @raises [Error] If parsing fails.
 			def parse_translation_unit(source_file, command_line_args = nil, unsaved = [], opts = {})
 				command_line_args = Array(command_line_args)
 				unsaved_files = UnsavedFile.unsaved_pointer_from(unsaved)
-
+				
 				translation_unit_pointer_out = FFI::MemoryPointer.new(:pointer)
-
+				
 				error_code = Lib.parse_translation_unit2(self, source_file, args_pointer_from(command_line_args), command_line_args.size, unsaved_files, unsaved.length, options_bitmask_from(opts), translation_unit_pointer_out)
 				if error_code != :cx_error_success
 					error_name = Lib::ErrorCodes.from_native(error_code, nil)
 					message = "Error parsing file. Code: #{error_name}. File: #{source_file.inspect}"
 					raise(Error, message)
 				end
-
+				
 				translation_unit_pointer = translation_unit_pointer_out.read_pointer
 				TranslationUnit.new translation_unit_pointer, self
 			end
-
+			
+			# Create a translation unit from a precompiled AST file.
+			# @parameter ast_filename [String] The path to the AST file.
+			# @returns [TranslationUnit] The loaded translation unit.
+			# @raises [Error] If loading the AST file fails.
 			def create_translation_unit(ast_filename)
 				translation_unit_pointer = Lib.create_translation_unit(self, ast_filename)
 				raise Error, "error parsing #{ast_filename.inspect}" if translation_unit_pointer.null?
 				TranslationUnit.new translation_unit_pointer, self
 			end
-
+			
 			private
-
+			
+			# Convert command line arguments to a pointer array for libclang.
+			# @parameter command_line_args [Array(String)] The command line arguments.
+			# @returns [FFI::MemoryPointer] A pointer to the arguments array.
 			def args_pointer_from(command_line_args)
 				args_pointer = MemoryPointer.new(:pointer, command_line_args.length)
-
+				
 				strings = command_line_args.map do |arg|
 					MemoryPointer.from_string(arg.to_s)
 				end
-
+				
 				args_pointer.put_array_of_pointer(0, strings) unless strings.empty?
 				args_pointer
 			end
-
+			
+			# Convert options hash to a bitmask for libclang.
+			# @parameter opts [Hash] The options hash.
+			# @returns [Integer] The bitmask representing the options.
 			def options_bitmask_from(opts)
 				Lib.bitmask_from(Lib::TranslationUnitFlags, opts)
 			end

data/lib/ffi/clang/lib/clang_version.rb

@@ -2,9 +2,9 @@
 
 # Released under the MIT License.
 # Copyright, 2014, by Masahiro Sano.
-# Copyright, 2014-2022, by Samuel Williams.
+# Copyright, 2014-2025, by Samuel Williams.
 
-require_relative 'string'
+require_relative "string"
 
 module FFI
 	module Clang

data/lib/ffi/clang/lib/code_completion.rb

@@ -2,31 +2,35 @@
 
 # Released under the MIT License.
 # Copyright, 2014, by Masahiro Sano.
-# Copyright, 2014-2022, by Samuel Williams.
+# Copyright, 2014-2025, by Samuel Williams.
 # Copyright, 2024, by Charlie Savage.
 
-require_relative 'cursor'
-require_relative 'diagnostic'
+require_relative "cursor"
+require_relative "diagnostic"
 
 module FFI
 	module Clang
 		module Lib
 			typedef :pointer, :CXCompletionString
-
+			
+			# FFI struct representing a single code completion result from libclang.
+			# @private
 			class CXCompletionResult < FFI::Struct
 				layout(
 					:kind, :cursor_kind,
 					:string, :CXCompletionString,
 				)
 			end
-
+			
+			# FFI struct representing the results of code completion from libclang.
+			# @private
 			class CXCodeCompleteResults < FFI::Struct
 				layout(
 					:results, :pointer,
 					:num, :uint,
 				)
 			end
-
+			
 			enum :completion_chunk_kind, [
 				:optional,
 				:typed_text,
@@ -50,13 +54,13 @@ module FFI
 				:horizontal_space,
 				:vertical_space
 			]
-
+			
 			CodeCompleteFlags = enum :code_complete_flags, [
 				:include_macros, 0x01,
 				:include_code_patterns, 0x02,
 				:include_brief_comments, 0x04
 			]
-
+			
 			CompletionContext = enum :completion_context, [
 				:unexposed, 0,
 				:any_type, 1 << 0,
@@ -83,7 +87,7 @@ module FFI
 				:natural_language, 1 << 21,
 				:unknown, ((1 << 22) - 1),
 			]
-
+			
 			# CXCompletionString functions
 			attach_function :get_completion_chunk_kind, :clang_getCompletionChunkKind, [:CXCompletionString, :uint], :completion_chunk_kind
 			attach_function :get_completion_text, :clang_getCompletionChunkText, [:CXCompletionString, :uint], CXString.by_value
@@ -95,7 +99,7 @@ module FFI
 			attach_function :get_completion_annotation, :clang_getCompletionAnnotation, [:CXCompletionString, :uint], CXString.by_value
 			attach_function :get_completion_parent, :clang_getCompletionParent, [:CXCompletionString, :pointer], CXString.by_value
 			attach_function :get_completion_brief_comment, :clang_getCompletionBriefComment, [:CXCompletionString], CXString.by_value
-
+			
 			# CXCodeCompleteResults functions
 			attach_function :get_code_complete_get_num_diagnostics, :clang_codeCompleteGetNumDiagnostics, [CXCodeCompleteResults.by_ref], :uint
 			attach_function :get_code_complete_get_diagnostic, :clang_codeCompleteGetDiagnostic, [CXCodeCompleteResults.by_ref, :uint], :CXDiagnostic
@@ -103,7 +107,7 @@ module FFI
 			attach_function :get_code_complete_get_container_kind, :clang_codeCompleteGetContainerKind, [CXCodeCompleteResults.by_ref, :pointer], :cursor_kind
 			attach_function :get_code_complete_get_container_usr, :clang_codeCompleteGetContainerUSR, [CXCodeCompleteResults.by_ref], CXString.by_value
 			attach_function :get_code_complete_get_objc_selector, :clang_codeCompleteGetObjCSelector, [CXCodeCompleteResults.by_ref], CXString.by_value
-
+			
 			# Other functions
 			attach_function :code_complete_at, :clang_codeCompleteAt, [:CXTranslationUnit, :string, :uint, :uint, :pointer, :uint, :uint], CXCodeCompleteResults.by_ref
 			attach_function :dispose_code_complete_results, :clang_disposeCodeCompleteResults, [CXCodeCompleteResults.by_ref], :void

data/lib/ffi/clang/lib/comment.rb

@@ -2,20 +2,22 @@
 
 # Released under the MIT License.
 # Copyright, 2013, by Carlos Martín Nieto.
-# Copyright, 2013-2022, by Samuel Williams.
+# Copyright, 2013-2025, by Samuel Williams.
 # Copyright, 2014, by George Pimm.
 # Copyright, 2014, by Masahiro Sano.
 
 module FFI
 	module Clang
 		module Lib
+			# FFI struct representing a comment in the libclang AST.
+			# @private
 			class CXComment < FFI::Struct
 				layout(
 					:ast_node, :pointer,
 					:translation_unit, :pointer
 				)
 			end
-
+			
 			enum :kind, [
 				:comment_null, 0,
 				:comment_text, 1,
@@ -31,36 +33,36 @@ module FFI
 				:comment_verbatim_line, 11,
 				:comment_full, 12,
 			]
-
+			
 			enum :render_kind, [
 				:normal,
 				:bold,
 				:monospaced,
 				:emphasized
 			]
-
+			
 			enum :pass_direction, [
 				:pass_direction_in, 0,
 				:pass_direction_out, 1,
 				:pass_direction_inout, 2
 			]
-
+			
 			# common functions
 			attach_function :comment_get_kind, :clang_Comment_getKind, [CXComment.by_value], :kind
 			attach_function :comment_get_num_children, :clang_Comment_getNumChildren, [CXComment.by_value], :uint
 			attach_function :comment_get_child, :clang_Comment_getChild, [CXComment.by_value, :uint], CXComment.by_value
 			attach_function :comment_is_whitespace, :clang_Comment_isWhitespace, [CXComment.by_value], :uint
-
+			
 			# TextComment functions
 			attach_function :text_comment_get_text, :clang_TextComment_getText, [CXComment.by_value], CXString.by_value
-
+			
 			# InlineCommandComment functions
 			attach_function :inline_command_comment_get_command_name, :clang_InlineCommandComment_getCommandName, [CXComment.by_value], CXString.by_value
 			attach_function :inline_command_comment_get_num_args, :clang_InlineCommandComment_getNumArgs, [CXComment.by_value], :uint
 			attach_function :inline_content_comment_has_trailing_newline, :clang_InlineContentComment_hasTrailingNewline, [CXComment.by_value], :uint
 			attach_function :inline_command_comment_get_render_kind, :clang_InlineCommandComment_getRenderKind, [CXComment.by_value], :render_kind
 			attach_function :inline_command_comment_get_arg_text, :clang_InlineCommandComment_getArgText, [CXComment.by_value, :uint], CXString.by_value
-
+			
 			# HTMLTagComment functions
 			attach_function :html_tag_comment_get_as_string, :clang_HTMLTagComment_getAsString, [CXComment.by_value], CXString.by_value
 			attach_function :html_tag_comment_get_tag_name, :clang_HTMLTagComment_getTagName, [CXComment.by_value], CXString.by_value
@@ -68,32 +70,32 @@ module FFI
 			attach_function :html_start_tag_comment_get_num_attrs, :clang_HTMLStartTag_getNumAttrs, [CXComment.by_value], :uint
 			attach_function :html_start_tag_comment_get_attr_name, :clang_HTMLStartTag_getAttrName, [CXComment.by_value, :uint], CXString.by_value
 			attach_function :html_start_tag_comment_get_attr_value, :clang_HTMLStartTag_getAttrValue,[CXComment.by_value, :uint], CXString.by_value
-
+			
 			# ParamCommandComment functions
 			attach_function :param_command_comment_is_direction_explicit, :clang_ParamCommandComment_isDirectionExplicit, [CXComment.by_value], :uint
 			attach_function :param_command_comment_get_direction, :clang_ParamCommandComment_getDirection, [CXComment.by_value], :pass_direction
 			attach_function :param_command_comment_get_param_name, :clang_ParamCommandComment_getParamName, [CXComment.by_value], CXString.by_value
 			attach_function :param_command_comment_is_param_index_valid, :clang_ParamCommandComment_isParamIndexValid, [CXComment.by_value], :uint
 			attach_function :param_command_comment_get_param_index, :clang_ParamCommandComment_getParamIndex, [CXComment.by_value], :uint
-
+			
 			# TParamCommandComment functions
 			attach_function :tparam_command_comment_get_param_name, :clang_TParamCommandComment_getParamName, [CXComment.by_value], CXString.by_value
 			attach_function :tparam_command_comment_is_param_position_valid, :clang_TParamCommandComment_isParamPositionValid, [CXComment.by_value], :uint
 			attach_function :tparam_command_comment_get_depth, :clang_TParamCommandComment_getDepth, [CXComment.by_value], :uint
 			attach_function :tparam_command_comment_get_index, :clang_TParamCommandComment_getIndex, [CXComment.by_value, :uint], :uint
-
+			
 			# BlockCommandComment functions
 			attach_function :block_command_comment_get_paragraph, :clang_BlockCommandComment_getParagraph, [CXComment.by_value], CXComment.by_value
 			attach_function :block_command_comment_get_command_name, :clang_BlockCommandComment_getCommandName, [CXComment.by_value], CXString.by_value
 			attach_function :block_command_comment_get_num_args, :clang_BlockCommandComment_getNumArgs, [CXComment.by_value], :uint
 			attach_function :block_command_comment_get_arg_text, :clang_BlockCommandComment_getArgText, [CXComment.by_value, :uint], CXString.by_value
-
+			
 			# VerbatimBlockLineComment functions
 			attach_function :verbatim_block_line_comment_get_text, :clang_VerbatimBlockLineComment_getText, [CXComment.by_value], CXString.by_value
-
+			
 			# VerbatimLineComment functions
 			attach_function :verbatim_line_comment_get_text, :clang_VerbatimLineComment_getText, [CXComment.by_value], CXString.by_value
-
+			
 			# FullComment functions
 			attach_function :full_comment_get_as_html, :clang_FullComment_getAsHTML, [CXComment.by_value], CXString.by_value
 			attach_function :full_comment_get_as_xml, :clang_FullComment_getAsXML, [CXComment.by_value], CXString.by_value

data/lib/ffi/clang/lib/compilation_database.rb

@@ -2,7 +2,7 @@
 
 # Released under the MIT License.
 # Copyright, 2014, by Masahiro Sano.
-# Copyright, 2014-2022, by Samuel Williams.
+# Copyright, 2014-2025, by Samuel Williams.
 
 module FFI
 	module Clang
@@ -10,23 +10,23 @@ module FFI
 			typedef :pointer, :CXCompilationDatabase
 			typedef :pointer, :CXCompileCommands
 			typedef :pointer, :CXCompileCommand
-
+			
 			CompilationDatabaseError = enum [
 				:no_error, 0,
 				:can_not_load_database, 1,
 			]
-
+			
 			# CompilationDatabase
 			attach_function :compilation_database_from_directory, :clang_CompilationDatabase_fromDirectory, [:string, :pointer], :CXCompilationDatabase
 			attach_function :compilation_database_dispose, :clang_CompilationDatabase_dispose, [:CXCompilationDatabase], :uint
 			attach_function :compilation_database_get_compile_commands, :clang_CompilationDatabase_getCompileCommands, [:CXCompilationDatabase, :string], :CXCompileCommands
 			attach_function :compilation_database_get_all_compile_commands, :clang_CompilationDatabase_getAllCompileCommands, [:CXCompilationDatabase], :CXCompileCommands
-
+			
 			# CompilationDatabase::CompileCommands
 			attach_function :compile_commands_dispose, :clang_CompileCommands_dispose, [:CXCompileCommands], :void
 			attach_function :compile_commands_get_size, :clang_CompileCommands_getSize, [:CXCompileCommands], :uint
 			attach_function :compile_commands_get_command, :clang_CompileCommands_getCommand, [:CXCompileCommands, :uint], :CXCompileCommand
-
+			
 			# CompilationDatabase::CompileCommand
 			attach_function :compile_command_get_directory, :clang_CompileCommand_getDirectory, [:CXCompileCommand], CXString.by_value
 			attach_function :compile_command_get_num_args, :clang_CompileCommand_getNumArgs, [:CXCompileCommand], :uint