Add missing documentation.

Author: samuel-williams-shopify

lib/db/postgres/adapter.rb

@@ -7,13 +7,19 @@
 
 module DB
 	module Postgres
+		# A database adapter for connecting to PostgreSQL servers.
 		class Adapter
+			# Initialize a new adapter with connection options.
+			# @parameter options [Hash] Connection options to be passed to the connection.
 			def initialize(**options)
 				@options = options
 			end
 
+			# @attribute [Hash] The connection options.
 			attr :options
 
+			# Create a new database connection.
+			# @returns [Connection] A new connection instance.
 			def call
 				Connection.new(**@options)
 			end

lib/db/postgres/connection.rb

@@ -9,14 +9,18 @@
 
 module DB
 	module Postgres
-		# This implements the interface between the underlying 
+		# A high-level database connection that implements the standardized connection interface.
+		# This class provides a bridge between the underlying native PostgreSQL interface and the DB gem's unified connection API.
 		class Connection < Async::Pool::Resource
+			# Initialize a new database connection.
+			# @parameter options [Hash] Connection options passed to the native connection.
 			def initialize(**options)
 				@native = Native::Connection.connect(**options)
 
 				super()
 			end
 
+			# Close the database connection and release resources.
 			def close
 				if @native
 					@native&.close
@@ -26,16 +30,26 @@ def close
 				super
 			end
 
+			# Get the type mapping for database types.
+			# @returns [Hash] The type mapping configuration.
 			def types
 				@native.types
 			end
 
+			# Append an escaped string value to the buffer.
+			# @parameter value [String] The string value to escape and append.
+			# @parameter buffer [String] The buffer to append to.
+			# @returns [String] The buffer with the escaped string appended.
 			def append_string(value, buffer = String.new)
 				buffer << @native.escape_literal(value)
 
 				return buffer
 			end
 
+			# Append a literal value to the buffer with appropriate formatting.
+			# @parameter value [Object] The value to append (supports Time, Date, Numeric, Boolean, nil, and strings).
+			# @parameter buffer [String] The buffer to append to.
+			# @returns [String] The buffer with the formatted value appended.
 			def append_literal(value, buffer = String.new)
 				case value
 				when Time, DateTime, Date
@@ -55,6 +69,10 @@ def append_literal(value, buffer = String.new)
 				return buffer
 			end
 
+			# Append an escaped identifier to the buffer.
+			# @parameter value [String | Array(String)] The identifier or array of identifiers to escape.
+			# @parameter buffer [String] The buffer to append to.
+			# @returns [String] The buffer with the escaped identifier appended.
 			def append_identifier(value, buffer = String.new)
 				case value
 				when Array
@@ -72,6 +90,11 @@ def append_identifier(value, buffer = String.new)
 				return buffer
 			end
 
+			# Generate a key column definition for table creation.
+			# @parameter name [String] The column name.
+			# @parameter primary [Boolean] Whether this is a primary key column.
+			# @parameter null [Boolean] Whether this column allows null values.
+			# @returns [String] The column definition string.
 			def key_column(name = "id", primary: true, null: false)
 				buffer = String.new
 
@@ -92,16 +115,22 @@ def key_column(name = "id", primary: true, null: false)
 				return buffer
 			end
 
+			# Get the current connection status.
+			# @returns [Symbol] The status symbol from the server.
 			def status
 				@native.status
 			end
 
+			# Send a query to the database server.
+			# @parameter statement [String] The SQL statement to execute.
 			def send_query(statement)
 				@native.discard_results
 
 				@native.send_query(statement)
 			end
 
+			# Get the next result set from a multi-result query.
+			# @returns [Native::Result | Nil] The next result set, or `nil` if no more results.
 			def next_result
 				@native.next_result
 			end
@@ -117,6 +146,7 @@ def next_result
 			)
 
 			# Database feature detection for migration and query building.
+			# @returns [DB::Features] The supported database features.
 			def features
 				FEATURES
 			end

lib/db/postgres/error.rb

@@ -5,6 +5,7 @@
 
 module DB
 	module Postgres
+		# An error raised by the PostgreSQL adapter.
 		class Error < StandardError
 		end
 	end

lib/db/postgres/native.rb

@@ -8,6 +8,7 @@
 
 module DB
 	module Postgres
+		# Provides FFI bindings to the native PostgreSQL client library (libpq).
 		module Native
 			extend FFI::Native::Library
 			extend FFI::Native::Loader

lib/db/postgres/native/connection.rb

@@ -10,7 +10,10 @@
 module DB
 	module Postgres
 		module Native
+			# Helper class for managing FFI string arrays.
 			class Strings
+				# Initialize a string array for FFI.
+				# @parameter values [Array] The array of values to convert to FFI strings.
 				def initialize(values)
 					@array = FFI::MemoryPointer.new(:pointer, values.size + 1)
 					@pointers = values.map do |value|
@@ -19,6 +22,7 @@ def initialize(values)
 					@array.write_array_of_pointer(@pointers)
 				end
 
+				# @attribute [FFI::MemoryPointer] The FFI array pointer.
 				attr :array
 			end
 
@@ -81,7 +85,13 @@ def initialize(values)
 			ffi_attach_function :PQescapeLiteral, [:pointer, :string, :size_t], :pointer, as: :escape_literal
 			ffi_attach_function :PQescapeIdentifier, [:pointer, :string, :size_t], :pointer, as: :escape_identifier
 
+			# A native FFI connection to the PostgreSQL client library.
 			class Connection < FFI::Pointer
+				# Establish a connection to the PostgreSQL server.
+				# @parameter types [Hash] Type mapping configuration.
+				# @parameter options [Hash] Connection options (database, username, password, host, port, etc.).
+				# @returns [Connection] A new connected instance.
+				# @raises [Error] If the connection fails.
 				def self.connect(types: DEFAULT_TYPES, **options)
 					# Postgres expects "dbname" as the key name:
 					if database = options.delete(:database)
@@ -121,13 +131,18 @@ def self.connect(types: DEFAULT_TYPES, **options)
 					return self.new(pointer, io, types)
 				end
 
+				# Initialize a native connection wrapper.
+				# @parameter address [FFI::Pointer] The pointer to the native connection.
+				# @parameter io [IO] The IO object for the socket.
+				# @parameter types [Hash] Type mapping configuration.
 				def initialize(address, io, types)
 					super(address)
 
 					@io = io
 					@types = types
 				end
 
+				# @attribute [Hash] The type mapping configuration.
 				attr :types
 
 				# Return the status of the connection.
@@ -152,6 +167,9 @@ def close
 					@io.close
 				end
 
+				# Escape a literal string value for safe inclusion in SQL queries.
+				# @parameter value [String] The value to escape.
+				# @returns [String] The escaped string with quotes.
 				def escape_literal(value)
 					value = value.to_s
 
@@ -164,6 +182,9 @@ def escape_literal(value)
 					return string
 				end
 
+				# Escape an identifier for safe inclusion in SQL queries.
+				# @parameter value [String] The identifier to escape.
+				# @returns [String] The escaped identifier with quotes.
 				def escape_identifier(value)
 					value = value.to_s
 
@@ -176,16 +197,23 @@ def escape_identifier(value)
 					return string
 				end
 
+				# Enable single row mode for streaming large result sets.
 				def single_row_mode!
 					Native.set_single_row_mode(self)
 				end
 
+				# Send a query to the server for execution.
+				# @parameter statement [String] The SQL statement to execute.
 				def send_query(statement)
 					check! Native.send_query(self, statement)
 
 					flush
 				end
 
+				# Get the next result set from a multi-result query.
+				# @parameter types [Hash] Type mapping to use for this result.
+				# @returns [Result | Nil] The next result set, or `nil` if no more results.
+				# @raises [Error] If the query resulted in an error.
 				def next_result(types: @types)
 					if result = self.get_result
 						status = Native.result_status(result)

lib/db/postgres/native/result.rb

@@ -38,7 +38,12 @@ module Native
 			ffi_attach_function :PQgetCopyData, [:pointer, :pointer, :int], :int, as: :get_copy_data
 			ffi_attach_function :PQfreemem, [:pointer], :void, as: :free_memory
 
+			# A result set from a database query with row iteration and type casting.
 			class Result < FFI::Pointer
+				# Initialize a new result set wrapper.
+				# @parameter connection [Connection] The connection that produced this result.
+				# @parameter types [Hash] Type mapping for field conversion.
+				# @parameter address [FFI::Pointer] The pointer to the native result.
 				def initialize(connection, types = {}, address)
 					super(address)
 
@@ -48,22 +53,33 @@ def initialize(connection, types = {}, address)
 					@casts = nil
 				end
 
+				# Get the number of fields in this result set.
+				# @returns [Integer] The field count.
 				def field_count
 					Native.field_count(self)
 				end
 
+				# Get the type converters for each field.
+				# @returns [Array] The array of type converter objects.
 				def field_types
 					field_count.times.collect{|i| @types[Native.field_type(self, i)]}
 				end
 
+				# Get the field names for this result set.
+				# @returns [Array(String)] The array of field names.
 				def field_names
 					field_count.times.collect{|i| Native.field_name(self, i)}
 				end
 
+				# Get the number of rows in this result set.
+				# @returns [Integer] The row count.
 				def row_count
 					Native.row_count(self)
 				end
 
+				# Cast row values to appropriate Ruby types.
+				# @parameter row [Array] The raw row data.
+				# @returns [Array] The row with values cast to proper types.
 				def cast!(row)
 					@casts ||= self.field_types
 
@@ -76,6 +92,9 @@ def cast!(row)
 					return row
 				end
 
+				# Iterate over each row in the result set.
+				# @yields {|row| ...} Each row as an array.
+				# 	@parameter row [Array] The current row data.
 				def each
 					row_count.times do |i|
 						yield cast!(get_row(i))
@@ -84,6 +103,10 @@ def each
 					Native.clear(self)
 				end
 
+				# Map over each row in the result set.
+				# @yields {|row| ...} Each row as an array.
+				# 	@parameter row [Array] The current row data.
+				# @returns [Array] The mapped results.
 				def map(&block)
 					results = []
 
@@ -94,6 +117,8 @@ def map(&block)
 					return results
 				end
 
+				# Convert the entire result set to an array.
+				# @returns [Array(Array)] All rows as arrays.
 				def to_a
 					rows = []