From 6ba0543a327c65de9917eb8fda035d0bf3e9116a Mon Sep 17 00:00:00 2001 From: William Storey Date: Thu, 15 Jan 2026 14:47:48 -0800 Subject: [PATCH 1/3] Add YARD documentation for undocumented modules and methods This brings the YARD documentation coverage from 92.19% to 100%. Modules documented: - Minfraud::Components: Container for request component classes - Minfraud::Components::Report: Components for the Report Transaction API - Minfraud::HTTPService: HTTP communication handling classes - Minfraud::Model: Response model classes for Score/Insights/Factors Methods documented: - Minfraud::Enum.included: Hook called when Enum module is included - Minfraud::Validates: All 16 validation helper methods now have documentation describing their purpose, parameters, and exceptions Co-Authored-By: Claude Opus 4.5 --- lib/minfraud/components/base.rb | 3 + lib/minfraud/components/report/transaction.rb | 1 + lib/minfraud/enum.rb | 6 + lib/minfraud/http_service/response.rb | 2 + lib/minfraud/model/abstract.rb | 3 + lib/minfraud/validates.rb | 136 ++++++++++++++++++ 6 files changed, 151 insertions(+) diff --git a/lib/minfraud/components/base.rb b/lib/minfraud/components/base.rb index cd282b24..06ccc4fd 100644 --- a/lib/minfraud/components/base.rb +++ b/lib/minfraud/components/base.rb @@ -1,6 +1,9 @@ # frozen_string_literal: true module Minfraud + # Components are used to build the request to the minFraud services. + # Each component represents a part of the transaction being analyzed, + # such as the device, account, email, or billing address. module Components # This is a parent class for all components. It defines a method which is # used for basic JSON representation of the component objects. diff --git a/lib/minfraud/components/report/transaction.rb b/lib/minfraud/components/report/transaction.rb index 57841306..a78ef915 100644 --- a/lib/minfraud/components/report/transaction.rb +++ b/lib/minfraud/components/report/transaction.rb @@ -2,6 +2,7 @@ module Minfraud module Components + # Components for the Report Transaction API. module Report # Contains the fields used in the Report Transaction API. # diff --git a/lib/minfraud/enum.rb b/lib/minfraud/enum.rb index 72414c23..b18f15eb 100644 --- a/lib/minfraud/enum.rb +++ b/lib/minfraud/enum.rb @@ -3,6 +3,12 @@ module Minfraud # Enum provides helpers for working with attributes with enumerated types. module Enum + # Hook method called when the module is included into a class. + # Extends the class with ClassMethods. + # + # @param base [Class] The class including this module. + # + # @return [nil] def self.included(base) base.extend(ClassMethods) end diff --git a/lib/minfraud/http_service/response.rb b/lib/minfraud/http_service/response.rb index 9e7a437d..fa5e71a6 100644 --- a/lib/minfraud/http_service/response.rb +++ b/lib/minfraud/http_service/response.rb @@ -7,6 +7,8 @@ require 'minfraud/model/score' module Minfraud + # HTTPService contains classes for handling HTTP communication with the + # minFraud web services. module HTTPService # Response class for HTTP requests. class Response diff --git a/lib/minfraud/model/abstract.rb b/lib/minfraud/model/abstract.rb index 049979ca..3fe53b8f 100644 --- a/lib/minfraud/model/abstract.rb +++ b/lib/minfraud/model/abstract.rb @@ -1,6 +1,9 @@ # frozen_string_literal: true module Minfraud + # Model contains classes for the minFraud response data. These classes + # represent the data returned by the Score, Insights, and Factors + # endpoints. module Model # @!visibility private class Abstract diff --git a/lib/minfraud/validates.rb b/lib/minfraud/validates.rb index 91f69978..7f067948 100644 --- a/lib/minfraud/validates.rb +++ b/lib/minfraud/validates.rb @@ -7,7 +7,19 @@ # rubocop:disable Metrics/ModuleLength module Minfraud # @!visibility private + # Validates provides validation helper methods for component input values. + # These methods are used internally when validation is enabled via + # Minfraud.enable_validation. module Validates + # Validates that a string value does not exceed a maximum length. + # + # @param field [String] The field name for error messages. + # @param length [Integer] The maximum allowed length. + # @param value [String, nil] The value to validate. + # + # @raise [InvalidInputError] If the value exceeds the maximum length. + # + # @return [nil] def validate_string(field, length, value) return if !value @@ -16,6 +28,14 @@ def validate_string(field, length, value) end end + # Validates that a value is a valid MD5 hash string. + # + # @param field [String] The field name for error messages. + # @param value [String, nil] The value to validate. + # + # @raise [InvalidInputError] If the value is not a valid MD5 hash. + # + # @return [nil] def validate_md5(field, value) return if !value @@ -24,6 +44,14 @@ def validate_md5(field, value) end end + # Validates that a value is a valid UUID string. + # + # @param field [String] The field name for error messages. + # @param value [String, nil] The value to validate. + # + # @raise [InvalidInputError] If the value is not a valid UUID. + # + # @return [nil] def validate_uuid(field, value) return if !value @@ -37,6 +65,14 @@ def validate_uuid(field, value) end end + # Validates that a value is a valid ISO 3166-2 subdivision code. + # + # @param field [String] The field name for error messages. + # @param value [String, nil] The value to validate. + # + # @raise [InvalidInputError] If the value is not a valid subdivision code. + # + # @return [nil] def validate_subdivision_code(field, value) return if !value @@ -45,6 +81,14 @@ def validate_subdivision_code(field, value) end end + # Validates that a value is a valid ISO 3166-1 alpha-2 country code. + # + # @param field [String] The field name for error messages. + # @param value [String, nil] The value to validate. + # + # @raise [InvalidInputError] If the value is not a valid country code. + # + # @return [nil] def validate_country_code(field, value) return if !value @@ -53,6 +97,15 @@ def validate_country_code(field, value) end end + # Validates that a value is a valid telephone country code (1-4 digits). + # + # @param field [String] The field name for error messages. + # @param value [String, nil] The value to validate. + # + # @raise [InvalidInputError] If the value is not a valid telephone country + # code. + # + # @return [nil] def validate_telephone_country_code(field, value) return if !value @@ -61,6 +114,15 @@ def validate_telephone_country_code(field, value) end end + # Validates that a value matches a regular expression pattern. + # + # @param field [String] The field name for error messages. + # @param regex [Regexp] The regular expression pattern to match. + # @param value [String, nil] The value to validate. + # + # @raise [InvalidInputError] If the value does not match the pattern. + # + # @return [nil] def validate_regex(field, regex, value) return if !value @@ -69,6 +131,14 @@ def validate_regex(field, regex, value) end end + # Validates that a value is a valid credit card token. + # + # @param field [String] The field name for error messages. + # @param value [String, nil] The value to validate. + # + # @raise [InvalidInputError] If the value is not a valid credit card token. + # + # @return [nil] def validate_credit_card_token(field, value) return if !value @@ -83,6 +153,14 @@ def validate_credit_card_token(field, value) end end + # Validates a custom input value (boolean, numeric, or string). + # + # @param field [String] The field name for error messages. + # @param value [Boolean, Numeric, String, nil] The value to validate. + # + # @raise [InvalidInputError] If the value is not valid. + # + # @return [nil] def validate_custom_input_value(field, value) return if !value @@ -101,6 +179,14 @@ def validate_custom_input_value(field, value) validate_string(field, 255, value) end + # Validates that a value is a valid IPv4 or IPv6 address. + # + # @param field [String] The field name for error messages. + # @param value [String, nil] The value to validate. + # + # @raise [InvalidInputError] If the value is not a valid IP address. + # + # @return [nil] def validate_ip(field, value) return if !value @@ -120,6 +206,15 @@ def validate_ip(field, value) nil end + # Validates that a value is a non-negative number within range. + # + # @param field [String] The field name for error messages. + # @param value [Numeric, nil] The value to validate. + # + # @raise [InvalidInputError] If the value is not a valid non-negative + # number. + # + # @return [nil] def validate_nonnegative_number(field, value) return if !value @@ -132,6 +227,15 @@ def validate_nonnegative_number(field, value) end end + # Validates that a value is a non-negative integer within range. + # + # @param field [String] The field name for error messages. + # @param value [Integer, nil] The value to validate. + # + # @raise [InvalidInputError] If the value is not a valid non-negative + # integer. + # + # @return [nil] def validate_nonnegative_integer(field, value) return if !value @@ -144,6 +248,14 @@ def validate_nonnegative_integer(field, value) end end + # Validates that a value is a valid email address or MD5 hash of one. + # + # @param field [String] The field name for error messages. + # @param value [String, nil] The value to validate. + # + # @raise [InvalidInputError] If the value is not a valid email or MD5 hash. + # + # @return [nil] def validate_email(field, value) return if !value @@ -155,6 +267,14 @@ def validate_email(field, value) validate_md5(field, value) end + # Validates that a value is in RFC 3339 date-time format. + # + # @param field [String] The field name for error messages. + # @param value [String, nil] The value to validate. + # + # @raise [InvalidInputError] If the value is not in RFC 3339 format. + # + # @return [nil] def validate_rfc3339(field, value) return if !value @@ -169,6 +289,14 @@ def validate_rfc3339(field, value) nil end + # Validates that a value is a boolean. + # + # @param field [String] The field name for error messages. + # @param value [Boolean, nil] The value to validate. + # + # @raise [InvalidInputError] If the value is not a boolean. + # + # @return [nil] def validate_boolean(field, value) return if !value @@ -177,6 +305,14 @@ def validate_boolean(field, value) end end + # Validates that a value is a valid absolute URI. + # + # @param field [String] The field name for error messages. + # @param value [String, nil] The value to validate. + # + # @raise [InvalidInputError] If the value is not a valid absolute URI. + # + # @return [nil] def validate_uri(field, value) return if !value From fee72544104967efb84848d97b7fe55d535a5a09 Mon Sep 17 00:00:00 2001 From: William Storey Date: Thu, 15 Jan 2026 14:56:46 -0800 Subject: [PATCH 2/3] Move rubocop directive inside Validates module The rubocop:disable comment placed before `module Minfraud` was being interpreted by YARD as documentation text, causing "rubocop:disable Metrics/ModuleLength" to appear on the Minfraud.html documentation page. Moving the directive inside the module (as part of the Validates module documentation block) prevents YARD from picking it up while still applying to the correct scope. Co-Authored-By: Claude Opus 4.5 --- lib/minfraud/validates.rb | 5 +++-- 1 file changed, 3 insertions(+), 2 deletions(-) diff --git a/lib/minfraud/validates.rb b/lib/minfraud/validates.rb index 7f067948..d801fccb 100644 --- a/lib/minfraud/validates.rb +++ b/lib/minfraud/validates.rb @@ -4,12 +4,13 @@ require 'ipaddr' require 'uri' -# rubocop:disable Metrics/ModuleLength module Minfraud # @!visibility private # Validates provides validation helper methods for component input values. # These methods are used internally when validation is enabled via # Minfraud.enable_validation. + # + # rubocop:disable Metrics/ModuleLength module Validates # Validates that a string value does not exceed a maximum length. # @@ -331,6 +332,6 @@ def validate_uri(field, value) end # rubocop:enable Style/RescueStandardError end + # rubocop:enable Metrics/ModuleLength end end -# rubocop:enable Metrics/ModuleLength From d4d704f1f0117405a5294d068e0af3dcb93c69a0 Mon Sep 17 00:00:00 2001 From: William Storey Date: Thu, 15 Jan 2026 15:02:27 -0800 Subject: [PATCH 3/3] Fix @return tag for Enum.included method The method returns the result of base.extend(ClassMethods), which returns the base class, not nil. Co-Authored-By: Claude Opus 4.5 --- lib/minfraud/enum.rb | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/lib/minfraud/enum.rb b/lib/minfraud/enum.rb index b18f15eb..3613ca21 100644 --- a/lib/minfraud/enum.rb +++ b/lib/minfraud/enum.rb @@ -8,7 +8,7 @@ module Enum # # @param base [Class] The class including this module. # - # @return [nil] + # @return [Class] The base class. def self.included(base) base.extend(ClassMethods) end