ffi-clang 0.13.0 → 0.14.0

data/lib/ffi/clang/comment.rb

@@ -2,20 +2,25 @@
 
 # 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.
 
-require_relative 'lib/cursor'
-require_relative 'lib/comment'
-require_relative 'source_location'
+require_relative "lib/cursor"
+require_relative "lib/comment"
+require_relative "source_location"
 
 module FFI
 	module Clang
-
+		# Represents a documentation comment in parsed source code.
+		# This class provides access to structured documentation comments extracted from C/C++ source code.
+		# Comments can have different kinds (text, inline commands, HTML tags, block commands, etc.) and can be hierarchical.
 		class Comment
 			include Enumerable
-
+			
+			# Build a comment instance from a low-level comment handle.
+			# @parameter comment [FFI::Pointer] The low-level comment handle.
+			# @returns [Comment] A comment instance of the appropriate subclass based on the comment kind.
 			def self.build_from(comment)
 				kind = Lib.comment_get_kind(comment)
 				case kind
@@ -49,219 +54,321 @@ module FFI
 					raise NotImplementedError, kind
 				end
 			end
-
+			
+			# Get the text content of this comment.
+			# @returns [String] The text content, empty string for base Comment class.
 			def text
 				return ""
 			end
-
+			
+			# Create a new comment instance.
+			# @parameter comment [FFI::Pointer] The low-level comment handle.
 			def initialize(comment)
 				@comment = comment
 			end
-
+			
+			# Get the kind of this comment.
+			# @returns [Symbol] The comment kind (e.g., :comment_text, :comment_paragraph).
 			def kind
 				Lib.comment_get_kind(@comment)
 			end
-
+			
+			# Get the number of child comments.
+			# @returns [Integer] The number of child comments.
 			def num_children
 				Lib.comment_get_num_children(@comment)
 			end
-
+			
+			# Get a specific child comment by index.
+			# @parameter n [Integer] The child index (defaults to 0).
+			# @returns [Comment] The child comment at the specified index.
 			def child(n = 0)
 				Comment.build_from Lib.comment_get_child(@comment, n)
 			end
-
+			
+			# Get all child comments.
+			# @returns [Array<Comment>] An array of all child comments.
 			def children
-				num_children.times.map { |i| child(i) }
+				num_children.times.map {|i| child(i)}
 			end
-
+			
+			# Check if this comment is whitespace only.
+			# @returns [Boolean] True if the comment contains only whitespace.
 			def whitespace?
 				Lib.comment_is_whitespace(@comment) != 0
 			end
-
+			
+			# Check if this comment has a trailing newline.
+			# @returns [Boolean] True if the comment has a trailing newline.
 			def has_trailing_newline?
 				Lib.inline_content_comment_has_trailing_newline(@comment) != 0
 			end
-
+			
+			# Iterate over all child comments.
+			# @yields {|comment| ...} Yields each child comment.
+			# 	@parameter comment [Comment] The child comment.
 			def each(&block)
 				num_children.times.map do |i|
 					block.call(child(i))
 				end
 			end
-
 		end
-
+		
+		# Represents an HTML tag in a documentation comment.
 		class HTMLTagComment < Comment
+			# Get the name of the HTML tag.
+			# @returns [String] The HTML tag name.
 			def name
 				Lib.extract_string Lib.html_tag_comment_get_tag_name(@comment)
 			end
 			alias_method :tag, :name
-
+			
+			# Get the text representation of this HTML tag.
+			# @returns [String] The HTML tag as a string.
 			def text
 				Lib.extract_string Lib.html_tag_comment_get_as_string(@comment)
 			end
 		end
-
+		
+		# Represents an HTML start tag in a documentation comment.
 		class HTMLStartTagComment < HTMLTagComment
+			# Check if this is a self-closing tag.
+			# @returns [Boolean] True if the tag is self-closing (e.g., <br/>).
 			def self_closing?
 				Lib.html_start_tag_comment_is_self_closing(@comment) != 0
 			end
-
+			
+			# Get the number of attributes on this tag.
+			# @returns [Integer] The number of attributes.
 			def num_attrs
 				Lib.html_start_tag_comment_get_num_attrs(@comment)
 			end
-
+			
+			# Get all attributes on this tag.
+			# @returns [Array<Hash>] An array of hashes with :name and :value keys.
 			def attrs
-				num_attrs.times.map { |i|
+				num_attrs.times.map {|i|
 					{
 						name: Lib.extract_string(Lib.html_start_tag_comment_get_attr_name(@comment, i)),
-						value: Lib.extract_string(Lib.html_start_tag_comment_get_attr_value(@comment, i)),
+							value: Lib.extract_string(Lib.html_start_tag_comment_get_attr_value(@comment, i)),
 					}
-			  }
+				}
 			end
 		end
-
+		
+		# Represents an HTML end tag in a documentation comment.
 		class HTMLEndTagComment < HTMLTagComment
 		end
-
+		
+		# Represents a paragraph comment containing text and inline content.
 		class ParagraphComment < Comment
+			# Get the text content by joining all child text with newlines.
+			# @returns [String] The paragraph text content.
 			def text
 				self.map(&:text).join("\n")
 			end
 		end
-
+		
+		# Represents a plain text comment.
 		class TextComment < Comment
+			# Get the text content of this comment.
+			# @returns [String] The text content.
 			def text
 				Lib.extract_string Lib.text_comment_get_text(@comment)
 			end
 		end
-
+		
+		# Represents an inline command comment (e.g., \c, \p).
 		class InlineCommandComment < Comment
+			# Get the command name.
+			# @returns [String] The inline command name (e.g., "c", "p").
 			def name
 				Lib.extract_string Lib.inline_command_comment_get_command_name(@comment)
 			end
-
+			
+			# Get the render kind for this inline command.
+			# @returns [Symbol] The render kind.
 			def render_kind
 				Lib.inline_command_comment_get_render_kind(@comment)
 			end
-
+			
+			# Get the number of arguments to this command.
+			# @returns [Integer] The number of arguments.
 			def num_args
 				Lib.inline_command_comment_get_num_args(@comment)
 			end
-
+			
+			# Get all arguments to this command.
+			# @returns [Array<String>] An array of argument strings.
 			def args
-				num_args.times.map { |i|
+				num_args.times.map {|i|
 					Lib.extract_string Lib.inline_command_comment_get_arg_text(@comment, i)
 				}
 			end
-
+			
+			# Get the text by joining all arguments.
+			# @returns [String] The joined argument text.
 			def text
 				args.join
 			end
 		end
-
+		
+		# Represents a block command comment (e.g., \brief, \return).
 		class BlockCommandComment < Comment
+			# Get the command name.
+			# @returns [String] The block command name (e.g., "brief", "return").
 			def name
 				Lib.extract_string Lib.block_command_comment_get_command_name(@comment)
 			end
-
+			
+			# Get the paragraph comment associated with this block command.
+			# @returns [Comment] The paragraph comment.
 			def paragraph
 				Comment.build_from Lib.block_command_comment_get_paragraph(@comment)
 			end
-
+			
+			# Get the text content from the paragraph.
+			# @returns [String] The text content.
 			def text
 				self.paragraph.text
 			end
 			alias_method :comment, :text
-
+			
+			# Get the number of arguments to this command.
+			# @returns [Integer] The number of arguments.
 			def num_args
 				Lib.block_command_comment_get_num_args(@comment)
 			end
-
+			
+			# Get all arguments to this command.
+			# @returns [Array<String>] An array of argument strings.
 			def args
-				num_args.times.map { |i|
+				num_args.times.map {|i|
 					Lib.extract_string Lib.block_command_comment_get_arg_text(@comment, i)
 				}
 			end
 		end
-
+		
+		# Represents a parameter documentation command (e.g., \param, \arg).
 		class ParamCommandComment < Comment
+			# Get the parameter name being documented.
+			# @returns [String] The parameter name.
 			def name
 				Lib.extract_string Lib.param_command_comment_get_param_name(@comment)
 			end
-
+			
+			# Get the documentation text for this parameter.
+			# @returns [String] The parameter documentation text.
 			def text
 				self.map(&:text).join("")
 			end
-
+			
 			alias_method :comment, :text
-
+			
+			# Check if the parameter index is valid.
+			# @returns [Boolean] True if the parameter index is valid.
 			def valid_index?
 				Lib.param_command_comment_is_param_index_valid(@comment) != 0
 			end
-
+			
+			# Get the parameter index in the function signature.
+			# @returns [Integer] The zero-based parameter index.
 			def index
 				Lib.param_command_comment_get_param_index(@comment)
 			end
-
+			
+			# Check if the parameter direction is explicitly specified.
+			# @returns [Boolean] True if the direction is explicit (e.g., [in], [out]).
 			def direction_explicit?
 				Lib.param_command_comment_is_direction_explicit(@comment) != 0
 			end
-
+			
+			# Get the parameter direction.
+			# @returns [Symbol] The direction (:in, :out, or :in_out).
 			def direction
 				Lib.param_command_comment_get_direction(@comment)
 			end
 		end
-
+		
+		# Represents a template parameter documentation command (e.g., \tparam).
 		class TParamCommandComment < Comment
+			# Get the documentation text for this template parameter.
+			# @returns [String] The template parameter documentation text.
 			def text
 				self.child.text
 			end
 			alias_method :comment, :text
-
+			
+			# Get the template parameter name being documented.
+			# @returns [String] The template parameter name.
 			def name
 				Lib.extract_string Lib.tparam_command_comment_get_param_name(@comment)
 			end
-
+			
+			# Check if the parameter position is valid.
+			# @returns [Boolean] True if the position is valid in the template parameter list.
 			def valid_position?
 				Lib.tparam_command_comment_is_param_position_valid(@comment) != 0
 			end
-
+			
+			# Get the nesting depth of this template parameter.
+			# @returns [Integer] The nesting depth.
 			def depth
 				Lib.tparam_command_comment_get_depth(@comment)
 			end
-
+			
+			# Get the index of this template parameter at the specified depth.
+			# @parameter depth [Integer] The nesting depth (defaults to 0).
+			# @returns [Integer] The index at the specified depth.
 			def index(depth = 0)
 				Lib.tparam_command_comment_get_index(@comment, depth)
 			end
 		end
-
+		
+		# Represents a verbatim block command comment (e.g., \code, \verbatim).
 		class VerbatimBlockCommandComment < Comment
+			# Get the text by joining all child lines with newlines.
+			# @returns [String] The verbatim block text.
 			def text
 				children.map(&:text).join("\n")
 			end
 		end
-
+		
+		# Represents a line within a verbatim block comment.
 		class VerbatimBlockLineComment < Comment
+			# Get the text of this line.
+			# @returns [String] The line text.
 			def text
 				Lib.extract_string Lib.verbatim_block_line_comment_get_text(@comment)
 			end
 		end
-
+		
+		# Represents a verbatim line comment (e.g., \code on a single line).
 		class VerbatimLine < Comment
+			# Get the text of this verbatim line.
+			# @returns [String] The verbatim line text.
 			def text
 				Lib.extract_string Lib.verbatim_line_comment_get_text(@comment)
 			end
 		end
-
+		
+		# Represents a complete documentation comment with all its components.
+		# This is the top-level comment structure that can be converted to HTML or XML.
 		class FullComment < Comment
+			# Convert this documentation comment to HTML.
+			# @returns [String] The HTML representation of the comment.
 			def to_html
 				Lib.extract_string Lib.full_comment_get_as_html(@comment)
 			end
-
+			
+			# Convert this documentation comment to XML.
+			# @returns [String] The XML representation of the comment.
 			def to_xml
 				Lib.extract_string Lib.full_comment_get_as_xml(@comment)
 			end
 			
+			# Get the text by collecting and joining all child text.
+			# @returns [String] The combined text content with newlines.
 			def text
 				self.children.collect{|child| child.text.strip}.join("\n")
 			end

data/lib/ffi/clang/compilation_database.rb

@@ -2,15 +2,20 @@
 
 # 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/compilation_database'
+require_relative "lib/compilation_database"
 
 module FFI
 	module Clang
+		# Represents a compilation database for a project.
 		class CompilationDatabase < AutoPointer
+			# Represents an error loading the compilation database.
 			class DatabaseLoadError < FFI::Clang::Error; end
-
+			
+			# Initialize a compilation database from a directory.
+			# @parameter dirpath [String] The directory path containing the compilation database.
+			# @raises [DatabaseLoadError] If the database cannot be loaded.
 			def initialize(dirpath)
 				uint_ptr = MemoryPointer.new :uint
 				cdb_ptr = Lib.compilation_database_from_directory(dirpath, uint_ptr)
@@ -20,88 +25,137 @@ module FFI
 				end
 				super cdb_ptr
 			end
-
+			
+			# Release the compilation database pointer.
+			# @parameter pointer [FFI::Pointer] The pointer to release.
 			def self.release(pointer)
 				Lib.compilation_database_dispose(pointer)
 			end
-
+			
+			# Get compile commands for a specific file.
+			# @parameter filename [String] The filename to get commands for.
+			# @returns [CompileCommands] The compile commands for the file.
 			def compile_commands(filename)
 				CompileCommands.new Lib.compilation_database_get_compile_commands(self, filename), self
 			end
-
+			
+			# Get all compile commands in the database.
+			# @returns [CompileCommands] All compile commands.
 			def all_compile_commands
 				CompileCommands.new Lib.compilation_database_get_all_compile_commands(self), self
 			end
-
+			
+			# Represents a collection of compile commands.
 			class CompileCommands < AutoPointer
 				include Enumerable
-
+				
+				# Initialize compile commands.
+				# @parameter pointer [FFI::Pointer] The commands pointer.
+				# @parameter database [CompilationDatabase] The parent database.
 				def initialize(pointer, database)
 					super pointer
 					@database = database
 				end
-
+				
+				# Release the compile commands pointer.
+				# @parameter pointer [FFI::Pointer] The pointer to release.
 				def self.release(pointer)
 					Lib.compile_commands_dispose(pointer)
 				end
-
+				
+				# Get the number of compile commands.
+				# @returns [Integer] The number of commands.
 				def size
 					Lib.compile_commands_get_size(self)
 				end
-
+				
+				# Get a compile command by index.
+				# @parameter i [Integer] The command index.
+				# @returns [CompileCommand] The compile command.
 				def command(i)
 					CompileCommand.new Lib.compile_commands_get_command(self, i)
 				end
-
+				
+				# Get all compile commands.
+				# @returns [Array(CompileCommand)] Array of compile commands.
 				def commands
-					size.times.map { |i| command(i) }
+					size.times.map {|i| command(i)}
 				end
-
+				
+				# Iterate over each compile command.
+				# @yields {|command| ...} Each compile command.
+				# 	@parameter command [CompileCommand] The compile command.
 				def each(&block)
 					size.times.map do |i|
 						block.call(command(i))
 					end
 				end
 			end
-
+			
+			# Represents a single compile command.
 			class CompileCommand
+				# Initialize a compile command.
+				# @parameter pointer [FFI::Pointer] The command pointer.
 				def initialize(pointer)
 					@pointer = pointer
 				end
-
+				
+				# Get the working directory for the command.
+				# @returns [String] The directory path.
 				def directory
 					Lib.extract_string Lib.compile_command_get_directory(@pointer)
 				end
-
+				
+				# Get the number of arguments.
+				# @returns [Integer] The number of arguments.
 				def num_args
 					Lib.compile_command_get_num_args(@pointer)
 				end
-
+				
+				# Get an argument by index.
+				# @parameter i [Integer] The argument index.
+				# @returns [String] The argument.
 				def arg(i)
 					Lib.extract_string Lib.compile_command_get_arg(@pointer, i)
 				end
-
+				
+				# Get all arguments.
+				# @returns [Array(String)] Array of arguments.
 				def args
-					num_args.times.map { |i| arg(i) }
+					num_args.times.map {|i| arg(i)}
 				end
-
+				
+				# Get the number of mapped sources.
+				# @returns [Integer] The number of mapped sources.
+				# @raises [NotImplementedError] This method is not yet implemented.
 				def num_mapped_sources
 					raise NotImplementedError
 					# Lib.compile_command_get_num_mapped_sources(@pointer)
 				end
-
+				
+				# Get a mapped source path by index.
+				# @parameter i [Integer] The source index.
+				# @returns [String] The mapped source path.
+				# @raises [NotImplementedError] This method is not yet implemented.
 				def mapped_source_path(i)
 					raise NotImplementedError
 					# Lib.extract_string Lib.compile_command_get_mapped_source_path(@pointer, i)
 				end
-
+				
+				# Get mapped source content by index.
+				# @parameter i [Integer] The source index.
+				# @returns [String] The mapped source content.
+				# @raises [NotImplementedError] This method is not yet implemented.
 				def mapped_source_content(i)
 					raise NotImplementedError
 					# Lib.extract_string Lib.compile_command_get_mapped_source_content(@pointer, i)
 				end
-
+				
+				# Get all mapped sources.
+				# @returns [Array(Hash)] Array of hashes with `:path` and `:content` keys.
+				# @raises [NotImplementedError] This method is not yet implemented.
 				def mapped_sources
-					num_mapped_sources.times.map { |i|
+					num_mapped_sources.times.map {|i|
 						{path: mapped_source_path(i), content: mapped_source_content(i)}
 					}
 				end